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PREFACE 

This book is intended as a compact reference guide to the Atari ST range of 
computers, it provides detailed information on the Atari ST hardware, an 
overview of the operating systems and the operating system calls. It also covers 
all types of machine including the Megas and blitters as well as the three 
generations of operating system used in the ST's todate: 

a) OS supplied on disk 

b) TOS in ROM 

c) 'New TOS' in ROM 

The majority of the book has been prepared in both decimal and hexadecimal 
notation to make reading and data entry less complicated for the beginner, and 
those who wish to use the VDI and AES tables from BASIC. I hope the use of 
decimal will not be too distressful to the purists, but most assemblers will accept 
either format as an input. The diagramatic presentation of data in memory and of 
stacks follows the Motorola MC68000 user's manual format of low memory 
towards the top of the page; presentation of memory maps follows the 
convention of high memory towards the top of the page. All memory 
representations are annotated to avoid confusion. 

The Atari ST range of computers contain one of the largest ROM's (192K) of 
the current range of home/low cost business computers available. This offers an 
enormous wealth of data and routines that the user may wish to access; about six 
times that of most computers. This information is presented in a condensed 
group tabular form to provide association between the different types of calls 
available, and to get it all in. General descriptions of all the facilities available 
(disk, file, interfaces etc) are provided to present the reader with at least an 
outline understanding of their operation. 

The book covers the programming of the Atari ST in three parts: 

Chapter 1 gives an overview of the Atari ST hardware and expansion ports, 
also included is a short description of the peripheral interface circuits. 

Chapter 2 presents an overview of the operating systems, the management of 
memory and resources, control of serial I/O, screen functions and file handling. 

The following chapters provide the operating system calls for the Atari OS, 
GEM, the line-A graphic functions, the intelligent keyboard command 
instructions and the blitter. 

The Appendices contain the system variables, configuration registers and a 
summary of the MC68000 instruction set. 
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Foreword 
by JackTramiel 


When we introduced the ST series of computers at Atari, we coined the 
phrase 'Power without the Price'. This sums up all that had been in our minds 
when we decided to design a range of powerful but low-cost machines that could 
be used for all applications ranging from sophisticated games to complex 
business and scientific uses. 

During the past few years, ever since I was responsible for bringing the first 
mass-produced electronic calculators and then the first true computers to the 
public at an affordable price, my whole aim has been to bring the benefits of 
technology to those of average income. We have to get high technology out of the 
hands of the few into the hands of the many. As I have said before we want 
'classes for the masses'. If you give somebody some sophisticated machinery then 
you'll be surprised what they can do with it. Time and again we have been 
amazed at what users have done with the technology when it is made freely 
available at an affordable price. 

And that brings me on to this series of books, edited by my old acquaintance 
Robin Bradbeer. It is impossible to give all the information necessary to 
completely cover all the uses of a computer in the instruction manual. Also, if 
more than one person explains something they bring out differing strengths of 
the system. This series of books should help all users of the ST to get to know the 
machine better and therefore use it more productively. Who knows, we at Atari 
may yet again be surprised by what you, the user, can do with the affordable 
technology that we have provided. 

Jack Tramiel 

1986 
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General Hardware Description 

The Atari ST computer system consists of a console unit featuring an integral 
keyboard, a display screen, sound subsystem, peripheral input/output and an 
operating system. Expansion ports are provided for the connection of a variety of 
peripheral devices i.e. a mouse, joystick, printer, modem, external floppy disk, 
ROM cartridge application program etc. 

The Atari ST console contains an 8MHz MC68000 16 bit microprocessor, at 
least 512K of resident RAM and a 192K ROM operating system. A Mostek 
MK68901 multi function peripheral (MFP) device provides the general purpose 
interrupt control and timers and a single direct main memory access channel, 
giving both high (hard disk) and low speed (external floppy disk) access support, 
through a 32-bit FIFO to the 8 bit device controllers. 

User input is via the integral intelligent keyboard, an external mechanical and 
or optical mouse, or a switch type joystick. The keyboard communicates with the 
main console section bidirectionally at 7 Kbits/s via a 1MHz HD6301 8 bit 
microprocessor in the keyboard unit, and a MC6850 asynchronous 
communications interface adapter (ACIA) in the console. 

The display may be either a monitor, high resolution black and white or 
colour (The Atari STM also caters for a standard television display unit). The 
console interrogates the display device to determine the type attatched, ensuring 
the high frequency sync signals are not sent to low frequency monitors. There are 
three display resolutions, 320x200 16 colour low resolution, 640x200 4 colour 
medium resolution and 640x400 high resolution monochrome. The display 
memory is part of the main memory and provides a matching bit-pixel 
relationship to the physical screen in high resolution mode. 

The music system sound effects and audio feedback output are created 
through the monitor or television speaker, at frequencies in the range of 30Hz to 
128Khz, via three independant voice channels. The programmable sound 
generator outputs may consist of a noise and a tone mixed at a fixed or variable 
amplitude defined by the envelope generator. 
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Main System and Device Subsystems 
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The musical instruments digital interface (MIDI) enables the ST to integrate 
with music synthesisers, sequencers, drum boxes etc. which incorporate the MIDI 
interface; enabling OMNI, POLY and MONO networking. 

Printer output is achieved via the parallel and RS232 interfaces, the latter also 
being available for modem and general communication. 

The floppy and hard disk interfaces provide the off-line data and program 
mass storage facilities. The hard disk drive interface is accessed through the DMA 
controller but the hard disk controller itself is off board. An on-board Western 
Digital WD1772A interfaces the floppy disk drive, which may be either integral 
or the Atari ST 31/2" disk drives SF 354 or SF 314. 

The operating system may be either in 192K of ROM, or an image file on disk, 
loaded by the disks boot sector, featuring the GEM operating environment of 
windows, icons, pull down menus. The ST is also supplied with two language 
implementations, an interpreted BASIC and Atari LOGO. 

The ST can accept other operating systems loaded via the boot sector or 
brought up by a driver in an 'AUTO' folder. 
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Atari ST Console I/O 


MONITOR/TV OUTPUT 


Monochrome Monitor Television 

Atari SM124 (where fitted) 

71.25 Hz scan rate 

RCA pin jack 

Colour Monitor Core : RF modulated video 

Atari SC1224 RGB Shield: Ground 

50/ 60 Hz scan rate 




13 way DIN 13S socket 


Sync 5V active low 3.3Kohm 
Audio IV pk-pk lOKohm 
Video IV pk-pk 75ohm 


Pin Function 

1 Audio out 

2 Composite video 

3 General purpose output 

4 Monochrome detect 

5 Audio in 

6 Green 

7 Red 

** 8 Ground 

10 Blue 

11 Monochrome 

12 Vertical sync 

13 Ground 


ST signal processing device 

(Reserved in older models) 

TTL PSG I/O A 

TTL MFP active low, IK pull up to 5 V 


(+12V, 10mA shell for SCART connector) 


** Note: Older versions of the ST reserved pin 2 and pin 8, this could be a 
source of trouble with some peripherals. Always use pin 13 for ground if possible 
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MONITOR OUTPUT 

The monitor output supports either a high resolution black and white 
monitor (Atari SM124) or a medium resolution colour monitor (Atari SC1224). 
Sound is reproduced through the display device speaker. 

Any suitable monitor may be attached, typical performance parameters of 
such monitors are as follows: 


Resolution 


Video Bandwidth 
Slot pitch (typ) 
Input video 
audio 

Sync 

Vertical scan 
Horizontal scan 


Low Medium High 

452x585 653x585 895x585 pixels 

lOMhz 18Mhz 18Mhz 
0.64mm 0.41mm 0.31mm 

1 VDC pk-pk 
1 VDC pk-pk 

5 VEXI active low 
50/60Hz 50/60Hz 71.2Hz 

15.7Khz 35.7Khz 
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PARALLEL PRINTER INTERFACE 


The parallel port interface 
provides an 8-bit data 
communication channel 

controlled by a strobe signal 
generated by the ST, indicating 
that data bits are available on 
the data lines for transfer to the 
peripheral, and a busy signal 
generated by the peripheral (usually a printer) indicating either that it is busy, 
has a fault or possibly out of paper if a printer. 


Pin Function 

1 Strobe 

2 Data 1 \ 

3 Data 2 I 

4 Data 3 I 

5 Data 4 I 

6 Data 5 I 

7 Data 6 I 

8 Data 7 I 

9 Data 8 / 

10 n.c 

11 Busy 
12-17 n.c 
18-25 Ground 

The parallel port strobe signal generated by the PSG I/O port A (pin 1), 
supplies the data transfer synchronization. The busy signal (pin 11) is read by the 
console MFP and provides the handshake control. 

The strobe signal is active low, the busy signal active high, with a IKohm pull 
up resistor to +5V. All signals are at TTL levels. 


Cooooooooooooo) 
\o OOOOOOOOOO 0/ 


25 14 

25 way DB 25S socket 

Data generated at a 
typical rate of 4kbytes/s 
by the PSG I/O port B 


Acknowledge is not supported 


1 Strobe 


2-9 Data 
1 1 Busy 

Main Console I/O port 
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RS232/MODEM INTERFACE 



2 Tx transmit The RS232 

3 Rx receive interface is controlled 

5 CTS clear to send via t h e PSG I/O port A 

8 DCD data carrier detect (RTS and DTR) and the 

22 Rl ring indicator MFP (CTS, DCD and 

RI) transmitting and 
receiving data within 

4 RTS ready to send *e range 50 to 192K 

20 DTR data terminal read^ au ^' timing 

synchronization is 
I/O port generated by the 

multi-function 

processor (MFP) timer D. (Only the 'New TOS' supports RTS/CTS handshaking.) 


Main Console 


The interface supports hardware handshake control: 

RTS \ Transmit CTS \ Receive 

DTR / PSG 1/ O port A DCD I MFP inputs 

Ring / 

and software control through Xon/Xoff protocol. 


Pin Function 

1 Grd Protective ground 

2 Tx Transmit data 

3 Rx Receive data 

4 RTS Ready to send 

5 CTS Clear to send 

6 n.c 

7 Gnd Signal ground 

8 DCD Data carrier detect 

9-19 n.c 

20 DTR Data terminal ready 

21 n.c 

22 Ri Ring indicator 

23-25 n.c 



25 14 


25 way DB 25P plug 


RS232 Signal Levels 

Zero +3v to +12v 
One -3v to-12v 
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FLOPPY DISK INTERFACE 


4 index pulse 

8 motor on 

9 direction in 

10 step 

1 2 write gate 

2 select side 

5 drive 0 

6 drive 1 

Main Console I/O port 



The floppy disk 
interface is based on 
an on-board Western 
Digital WD1772A disk 
controller and 

supports a maximum 
of two drives. There is 
no hardware sensing 
of disk removal. The 
drives provide fast 
storage and retrieval of 
data and programs on 
3 1/2" flexible micro 
disks. 


Note that the DIN socket shield must not be 
connected on the ST side 


Pin Function 

1 read data TTL active low, IK pull up 

2 select side 0 TTL active high (high sys reset) 

3 logic ground pair with read data 

4 index pulse TTL active low, IK pull up 

5 select drive 0 TTL active low (high sys reset) 

6 select drive 1 TTL active low (high sys reset) 

7 logic ground pair with write data 

8 motor on TTL active low \ 

9 direction in TTL active low I 

10 step TTL active low I -(inverted) 

11 write data TTL active low I 

12 write gate TTL active low / 

13 track 00 TTL active low, IK pull up 

14 write protect TTL active low, IK pull up 

Data is written to 512 byte sectors. 



14 way DIN 14S socket 
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DIRECT MEMORY ACCESS PORT 

This port can be used to provide access to a hard disk or a compact disk. The 
hard disk controller (target), not supplied with the basic ST system, is 
communicated with by a sequence of six bytes (from initiator system) which 
provides format, read and write facilities etc. in one direction only. The command 
protocol used is referred to as ANSI X3T9.2, a SCSI-like small computer systems 
interface, of which the ST supports a small subset. 

The Atari hard disk descriptor block consists of a six byte command packet 
conforming to the following: 

Six byte command packet 


Byte Bit 
no. no. 

Function 

range 

— 0 0 1 ? 

5-7 

1 0-4 

5- 7 

2 0-5 

6- 7 

3 0-7 

4 0-7 

5 0-7 

Uperation code 0-31 

Controller number 0-7 
Head number 0-31 

Drive number 0-7 

Sector number 0-63 

Cylinder number high 
Cylinder number low 
Sector count 
Control byte 


Hard disk command code summary 


Op code 
Dec Hex 

Command 

5 05 

6 06 
8 08 

10 0A 

11 0B 
13 0D 
26 1A 

Verify track \ Multi-sector 

Format track 1 _ transfer 
Read sector 1 with 

Write sector / implied seek 

Seek 

Correction pattern 
Mode sense 


There is only one DMA channel, it is shared by both high speed (upto 
8Mbit/ s) and low speed (250 to 500Kbit/s) 8-bit device controllers. 
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DMA interface port socket 

10 1 

(o 0 o o o o o o o o) 

\o OOOOOOO 0/ 

19 11 

19 way DB 19S socket 


Pin 

Function 

Signal type 

1 

data 0 \ 


2 

data 1 1 


3 

data 2 1 


4 

data 3 1 _ 

TTL 

5 

data 4 1 


6 

data 5 1 


7 

data 6 1 


8 

data 7 / 


9 

chip select 

TTL active low 

10 

interrupt request 

TTL active low, IK pull up 

11 

ground 


12 

reset 

TTL active low (system reset) 

13 

ground 


14 

acknowledge 

TTL active low 

15 

ground 


16 

A1 

TTL 

17 

ground 


18 

read /write 

TTL 

19 

data request 

TTL active low, IK pull up 


The 'New TOS' supports more than one device attatched to the DMA port, 
without the need for special software, on power up. 
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MUSICAL INSTRUMENT INTERFACE (MIDI) 


Rx receive data 
return 


The MIDI interface functions through an MC6850 asynchronous 
communications interface adaptor (ACIA) whose control/status register is 
located at $FFFC04 (16776196); data is passed in the register at offset 2 from the 
control/status register. 

Data is transmitted serially via the MIDI ports through two pins 
asynchronously using the protocol: 

One start bit, 8 data bits. One stop bit and no parity at 31.25 Kbaud. 

The MIDI OUT port also supports the optional through port which merely 
provides the MIDI IN signals through an opto-coupled isolator at the MIDI OUT 
connector. 



Main Console 


I/O oort 


Control of the port is available through the ST's extended BIOS. 


MIDI in 



5 way DIN 5S socket 


MIDI out 



5 way DIN 5S socket 


Pin 

1 

2 

3 

4 

5 


Function 

n.c 

n.c 

n.c 

In rx data 
In loop return 


Pin Function 

1 Thru tx data 

2 Shield ground 

3 Thru loop return 

4 Out tx data 

5 Out loop return 


The Midi ports may be used to network data between connected computers, 
they operate in RS232 current loop mode'. That is; 

Signal levels zero 5ma 

one zero current 
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PLUG-IN CARTRIDGE PORT 


This port provides a plug-in cartridge facility that does not sense in hardware 
the presence of a cartridge. The cartridge ROM occupies addresses in the range: 

SFAOOOO (16384000) to $FBFFFF (16515071) - 128 Kbyte, Bank switching 
provides a means of accessing even more. 


1 39 

jiiiiiiiiililiiiiiiiiiiiiiiiiiiiiiiii>nL^ 

niniiiiiiiiiiiiiiiuniiiniiiiMiii'hr 

2 40 

40 way socket 


Pin 

Function 

Pin 

Function 


1 

power +5 Vdc 

21 

address 

8 

2 

power +5 Vdc 

22 

address 

14 

3 

data 14 

23 

address 

7 

4 

data 15 

24 

address 

9 

5 

data 12 

25 

address 

6 

6 

data 13 

26 

address 

10 

7 

data 10 

27 

address 

5 

8 

data 11 

28 

address 

12 

9 

data 8 

29 

address 

11 

10 

data 9 

30 

address 

4 

11 

data 6 

31 

ROM3 select 

12 

data 7 

32 

address 

3 

13 

data 4 

33 

ROM4 select 

14 

data 5 

34 

address 

2 

15 

data 2 

35 

upper data strobe 

16 

data 3 

36 

address 

1 

17 

data 0 

37 

lower data strobe 

18 

data 1 

38 

ground 


19 

address 13 

39 

ground 


20 

address 15 

40 

ground 



Only the lower 15 address lines are available to the ROM cartridge which 
does not provide a 'write' line. 
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INTELLIGENT KEYBOARD (ikbd) INTERFACE 

The Atari intelligent keyboard performs a variety of functions that include 
the decoding of the key switch matrix, decoding mouse, trackerball and joystick 
data and providing the time of day. It communicates with the main processor 
over a high speed bi-directional serial link providing a convenient 
mouse /joystick interface. 

The keyboard consists of a series of make/break key switches for which the 
ikbd generates keyboard scan codes for each key press and release, chosen 
mainly for compatibility with the Digital Research graphic system (GSX). The key 
codes, table Appx D.4, are defined for the whole range of international keyboards 
such that each code has a predefined key press meaning, irrespective of the 
presence of the key switch. The break code for each key is signified by bit 7 of the 
corresponding make code for the key being set; the codes #$F6 to #$FF are 
reserved for keyboard system functions. 

The keyboard controller contains a 1 MHz HD6301 8-bit microprocessor that 
communicates with the ST's MC6850 asynchronous communications interface 
adaptor (ACIA) at a fixed 7.8 Kbit/s. The keyboard not only transmits the 
encoded key scan codes (with a two key rollover), it also enables the programmer 
to interrogate the status, define the read rates and sensitivity of the mouse and 
joysticks under software control. 

The time-of-day clock incorporated in the keyboard controller is held to a 
resolution of 1 second and may be read and set from software. The keyboard may 
be reset, without affecting the time held by the clock, to its power-up parameters. 

When reset, the keyboard controller performs a simple ROM (checksum), 
RAM and key (stuck) series of checks, correct operation is indicated by the return 
of the version /release number of the ikbd controller. 
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MOUSE/JOYSTICK INTERFACE 


The mouse and joysticks work on the basic unit of an 'event', this is defined 
as either the opening or closing of a switch, or of motion beyond a predefined 
programmable threshold level. The mouse is capable of a resolution of 200 events 
per inch (4 events/mm) and is scanned at such a rate as to permit tracking 
velocities of up to 10 in/s (250mm/s). 

Motion, which produces make then break cursor keycodes, can be reported in 
three different ways; relative, absolute and cursor key motion (motion per 
keystroke is independently programmable in both axes). The mouse buttons can 
also be treated as part of the mouse or as additional keyboard keys. 



1 

c# • 

5 

• • •) 

Port 0 is configured 


v . 

• ./ 

for mouse operation 


6 

9 

Port 1 is the second 


9 way DB 9P plug 

joystick interface 

Pin 

Joystick 

Function 

Mouse/Jstk 0 
Function 


1 

Up 

XB/Up 

The mouse unit provides 
interactive input to programs 

2 

Down 

XA/Down 

like the desktop applications. 

3 

Left 

YA/Left 

permitting a convenient method 

4 

Right 

YB/Right 

of selecting from a menu of 

5 

reserved 

n.c 

facilities shown symbolically 

6 

Fire 

left button/Fire 

as icons or simply as text. 

7 

Power 

+5v 

Port zero is configured for 

8 

Gnd 

Gnd 

the mouse, but may also be 

9 

n.c 

right button/Joy 1 fire connected to a joystick. 


The joystick is invariably used in games applications; but may also be used 
instead of the cursor keys, for fine control of the screen cursor position (one pixel 
movement). 

The joystick fire and mouse buttons close to ground. 
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POWER SUPPLY 

The seperate power supply provides power for the main system board, the 
keyboard controller, any connected expansion ROM and expansion RAM. 

The supply is fused, the levels are regulated for over-voltage and incorporate 
over-current protection. 



Pin 

1 +5 VDC 

2 n.c 

3 Ground 

4 +12 VDC 

5 -12 VDC 

6 +5 VDC 

7 Ground 


The power levels are: 


5VDC @ 3A 5% 
+12VDC @ 0.03 A 10% 
-12 VDC @ 0.03 A 10% 


The power supply may be integral with the main unit (1040ST, Mega ST). 
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PROCESSOR DEVICE OUTLINES 


MC68000 8 MHz microprocessor 

WD1772A floppy disk controller 

MK68901 multi-function processor 

MC6850 asynchronous communications interface adaptor 

YM2149 programmable sound generator 


CUSTOM DESIGNED DEVICES (ULAS) 

Direct memory access controller (DMA) 

Memory management unit (MMU) 

Video controller (Shifter) 

General housekeeping (Glue) 

Blitter 


There have been three generations of operating system for the Atari ST 
todate: 

a) OS supplied on disk 

b) TOS in ROM 

c) 'New TOS' in ROM 


The blitter chip requires the 
necessarily require the blitter chip. 


'New TOS', but the 'New TOS' does not 
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MOTOROLA MC68000 MICROPROCESSOR 
Signal I/O 

The following is a very brief description of the signal I/O of the Motorola 
MC68000. 


Vcc — 
Ground — 
Clock 


Processor 

status 


FCO -\ 
FC1 -\ 
FC2 -4 


Synchronous 

control 


System 

control 


Berr — 
RESET - 
HALT 


AO 

to Address bus 
I— A23 


00 / 

to O Data bus 
1— D15 ^ 

r— \ Asynchronous 
D- / control 

I — \ Bus arbitration 
*— / control 

P Iph? Interrupt 
|p |_2 J control 


O 

O 


A high-density, N-channel, silicon-gate depletion load 16-bit Microprocessor 
in a 64 pin DIL package. 

The Address bus (AO - A23) enables the MC68000 to address 16 megabyte of 
data or 8 Megaword of instructions. The address bus provides the level being 
serviced, during an interrupt, on address lines AO to A3 while A4 to A23 are held 
high. 

The Data bus (DO - D15) enables the transfer of word and byte-sized chunks 
of data. During an interrupt acknowlege, a vector number may be placed on lines 
DO to D7 by a peripheral device. 
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Bus arbitration control allows a peripheral device to control the MC68000 
bus (bus master); any external request will be granted on a priority basis between 
the competing devices. 

Interrupt control provides a priority level from peripherals requesting 
processor control enabling selection of multiple interrupts on a priority basis. 
Zero implies that there is no interrupt present and 7 is a non maskable interrupt. 


Level 

Autovector 

7 high 

Non maskable interrupt 

6 

MC68901 multi function processor 

5 

- 

4 

Vertical blanking sync 

3 

- 

2 

1 low 

Horizontal blanking sync. 


System control informs the processor that bus errors have occurred and also 
resets or halts the processor. 

Processor status: each time a memory or I/O call is made the processor 
provides the following information on the processor status lines to a peripheral 
device: whether the processor is accessing data or program memory space or 
servicing an interrupt; and whether the processor is in user or supervisor mode. 

The Motorola MC68000's separate parallel address and data buses are used to 
transfer data using an asynchronous bus structure controlled by the processor, 
internal or external, which has current bus control. 

Interfacing with the 8-bit M6800 and 6500 family of synchronous peripheral 
devices is catered for through the use of memory-mapped I/O and a modified 
bus cycle. 
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WD1772A FLOPPY DISK CONTROLLER 


$FF8604 
Access 
data 
byte 

$FF8606 
Mode 
control 

C 

ommands are passed to the FDC (and an external HDC), by selecting the 
appropriate FDC or HDC function (Read status/write command, sector, track or 
data) through the configuration register ($FF8606) and sending instructions or 
data via the access byte (SFF8604). 



MODE BYTE ($FF8606) 


Bits Register 


..10 

Read 

Write 

00 

Status 

Command 

0 1 

Track 

Track 

1 0 

Sector 

Sector 

1 1 

Data 

Data 


Bit 7 selects Write (1 ) or Read (0) 

The WD1772A floppy disk controller supports eleven instructions, these 
should only be loaded into the data byte register when the status bit (bit 5, 
$FFFA01) is off. The instructions enable head location, reading and writing 
sectors, tracks and the forced interrupt of a disk operation: 
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INSTRUCTION BYTE ($FF8604) 

Type 1 command 

0 0 0 0 .... Restore \ To track 0 position 

00 0 1 .... Seek / Track position 

00 1 Step Towards last track 

0 10 Step in Towards inner track 

011 Step out Towards outer track 

1 .... Update track register Toggle bit 

0 ..00 2ms \ 

0 ..01 3ms Step 

0 ..10 12ms rate 

0 ..11 6ms / 

0 . 1 . . With verify \ Toggle 

0 1 . . . Without Spin-up disable / bits 


Type 2 command 

1 0 0 Read Sector 

10 1 Write Sector 


... 1 write 'deleted data’ mark 
. . 1 • precompensation enabled 
■ 1 . . 30ms delay 
1 • • • without 'spin-up' delay 
• • • 1 • ■ ■ ■ multiple sector read/write , 


Toggle 

hits 


Type 3 command 

110. ..00 Read address Read diskette ID 

111. ..00 Read track 

1111 0 Write track 

... 1 write 'deleted data’ mark \ 

• • 1 • precompensation enabled Toggle 
. 1 . . 30ms delay bits 

1 . . . without 'spin-up' disable / 


Type 4 command 

110 1 ..00 Force interrupt 

0 0.. end with no interrupt 
0 1.. interrupt on index pulse 
10.. immediate interrupt 
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MC68901 MULTI-FUNCTION PROCESSOR 


Reset 

Internal 
control logic 


Data - 
( 8 ) - 

RSI - 
RS5 - 

CS - 
R/W- 
DS - 
DTACK- 



IEO IACK 


TCO 

TDO 

Xtall 


OSCL xtal2 


TAO 

TAI 

TBO 

TBI 


- Serial in 

- Tx clock 

. IOA _.^ • Serial out 
USARTj_ Seria | dock 

• Rx ready 
J— Tx ready 


I/O b 


10-17 


Daisy chain 


Bit I/O interrupts 
& modem control 


The MC68901 contains a single channel USART capable of operating in full 
duplex, at a rate of 62.5Kb/s asynchronous, IMb/s synchronous from an internal 
or external Baud rate generator. The USART also supports DMA handshake 
signals and modem control. 

There are four timers with independant operation and vectored interrupts, 
the timers have the following preferred timer uses: 

Timer A: Stand alone applications and independent software vendor. 

B: Primarily Screen Graphics (hblank, sync etc.) 

C: System timing (GSX, GEM, Desktop, etc). Suitable for delays and 

general timing applications (200Hz). 

D: RS 232 port baud rate control. 

Eight individually programmable I/O pins with interrupt capabilities are also 
available. 
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MC68901 INTERRUPT CONTROL 


MFP HARDWARE BOUND INTERRUPTS 


Priority 

Function 

15 high 

Monochrome monitor detect 

GPI (7) 

14 

RS232 ring indicator 

GPI (6) 

13 

Timer A 

Timer A 

12 

RS232 receive buffer full 


11 

RS232 receive error 


10 

RS232 transmit buffer empty 


9 

RS232 transmit error 


8 

Horizontal blanking counter 

Timer B 

7 

FDC/HDC - Interrupt 

GPI (5) 

6 

^Keyboard and MIDI 

GPI (4) 

5 

Timer C (system clock) 

Timer C 

4 

RS232 baud rata generator 

Timer D 

3 

Blitter interrupt (reserved) 

GPI (3) 

2 

RS232 clear to send 

GPI (2) 

1 

RS232 data carrier detect 

GPI (1) 

0 low 

Parallel port busy 

GPI (0) 


* Test MC6850 status bit to differentiate between keyboard and MIDI interrupts. 

MFP CONFIGURATION REGISTERS 

These are located at address $FFFA01-1 6775681 and may be accessed via the 
following offsets: 


Offset Function 

Dec Hex 

Offset Function 

Dec Hex 

1 

01 

Gen purpose 1/ O 

25 

19 

Timer A control 

3 

03 

Active edge 

27 

IB 

Timer B control 

5 

05 

Data direction 

29 

ID 

Timer C & D control 

7 

07 

Interrupt enable A 

31 

IF 

Timer A data 

9 

09 

Interrupt enable B 

33 

21 

Timer B data 

11 

0B 

Interrupt pending A 

35 

23 

Timer C data 

13 

0D 

Interrupt pending B 

37 

25 

Timer D data 

15 

OF 

Interrupt m-serv A 

39 

27 

Sync character 

17 

11 

Interrupt in-serv B 

41 

29 

Usart control 

19 

13 

Interrupt mask A 

43 

2B 

Receiver status 

21 

15 

Interrupt mask B 

45 

2D 

Transmitter status 

23 

17 

Vector base address 

47 

2F 

Usart data 


1.24 




The Atari ST Hardware 


The MC68901 usart registers are accessible from Extended BIOS (XBIOS) 


SYNCHRONOUS CHARACTER REGISTER 

I7I6I5I413I2I1 101 SCR = $FFFA27 
Used to synchronize incoming received data acting as the matching character 


USART CONTROL REGISTER 


I 7 I 6 I 5 


4 13 12 11 


Ton UCR = $FFFA29 
= odd, 1 = even 


6 = off, 1 = enable 


1 1 - async 

1 0 - async 

0 1 - async 
0 Q - sync 


Start 1 2 

and 1 1/2 used by div by 16 

stop 1 1 

bits 0 0 


6 0-8 bits per word 

0 1-7 bits per word 

1 0-6 bits per word 

1 1-5 bits per word 


0 = normal, 1 = Divide by 16 


TRANSMIT STATUS REGISTER 




5 I 4 I 3 I 2 I 1 lOl TSR = $FFFA2D 


nr 


0 = disable Tx and clear flag 

1 = enable normal operations 


high imp 
low 
high 


Configure Tx 
o/p when 
Tx disabled 


loopback async (connect o/p to i/p) 


0 Normal Tx 
I 1 Send a break 

0 Tx enabled 

1 Tx disabled after last character sent 

0 Disable Tx 

1 Enable Rx when Tx disabled after last character sent 


0 Tx status register read 

1 Word transmitted and Tx buffer empty 


0 Tx buffer read 

1 Tx word transferred to Tx shift register 


Interrupt 

generated 


9 


10 

9 
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Timer A uses register B ($FFFA19), timer B register 14 ($FFFA1B), timers C 
and D both use register 15 ($FFFA1D). Timer C bits 4 to 6 and timer D bits 0 to 2, 
both operate delay mode only. 


0 0 0 0 Timer stop 

1 0 0 0 Event # 



1 
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MC6850 ASYNCHRONOUS COMMUNICATIONS 
INTERFACE ADAPTOR 



The MC6850 ACIA provides data formatting and control of a serial interface 
to an 8-bit bidirectional data bus. At the bus interface, the four ACIA registers, 
the status and receive data -read only and the control and transmit data-write 
only registers, appear as two addressable memory locations. 

The programmable ACIA control register, which sets the format of the serial 
link, is located at $FFFC00 (16776192) for the intelligent keyboard serial 
communications link, and at $FFFC04 (16776196) for the MIDI interface. 

The ACIA supports peripheral/ modem control through: 

RTS request to send, 

CTS clear to send 
and DCD data carrier detect. 

Protocols for 8 and 9 bit transmission using an optional odd or even parity, 
and one or two stop bits, are available through the programmable control 
register. 

The MIDI port may be configured as a second serial port (for networking) but 
the intelligent keyboard interface is not accessible. 
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ACIA CONTROL/STATUS REGISTER 


’READ’ 

RECEIVE STATUS 
REGISTER 


: H6 | 5 | 4 1 3 | 2 | 1 J. 0 [ $FFFC00 - $FFFC04 

0 0 \ normal \ Divide 

0 1 ] Div by 1 6 ) select 

1 0 / Div by 64 / bits 

1 1 Master reset 

0 0 0 7 bits, even, 2 stop bits 

0 0 1 7 bits, odd, 2 stop bits 

0 10 7 bits, even, 1 stop bit 

0 117 bits, odd, 1 stop bit ’WRITE’ 

1 0 0 8 bits, 2 stop bits TRANSMIT CONTROL 

10 1 8 bits, 1 stop bit REGISTER 

110 8 bits, even, 1 stop bit 

111 8 bits, odd, 1 stop bit 

0 0 RTS low, Tx interrupt disable 

0 1 RTS low, Tx interrupt enable 

1 0 RTS high, Tx interrupt disable 

1 1 RTS low, Tx a break onto data output. Tx interrupt disable 

0_Rx interrupt disable 

1_Rx interrupt enable (Rx data register full overrun. DCD low to high transition) 


Interrupt request 
Parity error 

Rx overrun (character lost) 

Framing error 
CTS 
DCD 

Tx data register empty 
Rx data register full 
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YAMAHA YM2149 PROGRAMMABLE SOUND 
GENERATOR 


Channel 

Channel 

Channel 


A 

B 

C 


TONE/ 


TONEh 


TONE! 


Mixer 


AW(P- 

-|amp- 

-(AMfi- 


D/A 


D/A 


D/A 


Sound 
O/P 
Port 




ENVELOPE 

NOISE 


Generator 


CPU bus 


CPU bus 



I/O 



Reaister 




I/O 



Reaister 



8 bit I/O 
port A 

8 bit I/O 
port B 


The programmable sound generator control registers are located as follows: 

RAM offset Function . Bits used 

reg add} Base address SFF8800-1 6746596 | 7 6 5 4 321 Q 


0 0 Channel A fine tune 

1 1 Channel A coarse tune 

2 2 Channel B fine tune 

3 3 Channel B coarse tune 

4 4 Channel C fine tune 

5 5 Channel C coarse tune 

6 6 Noise period 

7 7 Mixer cntrl-I/O enable 

Fixed amplitude 

8 8 Channel A amplitude 

9 9 Channel B amplitude 

10 A Channel C amplitude 

Variable amplitude 

11 B Envelope period fine 

12 C Envelope period coarse 

13 D Envelope shape 

14 E I/O port A (output only) 

15 F I/O port B (centronics) 

M=mode fixed/variable C=cycle A=alternate x: 


X X X X 

X X X X 


X X X X 

X X X X 

X X X X 


X X X X 

X X X X 

X X X X 


X X X X 

X 

X X X X 

I/O noise tone 

M 

X X X X 

M 

X X X X 

M 

X X X X 

X X X X 

X X X X 

X X X X 

X X X X 


CRAH 

data 


hits used R= 

=ramp H=hold 
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DIRECT MEMORY ACCESS CONTROLLER (DMA) 


R /W 

1 1 

40 

+5v 

A1 

2 

39 

elk 8Mhz 

FCS 

3 

38 

RDY 

DO 

4 

37 

ACK 

D1 

5 

36 

CD0 

D2 

6 

35 

CD1 

D3 

7 

34 

CD2 

D4 

8 

33 

CD3 

D5 

9 

32 

CD4 

D6 

10 

31 

CD5 

D7 

11 

30 

CD6 

D8 

12 

29 

CD7 

D9 

13 

28 

Gnd 

D10 

14 

27 

CA2 

Dll 

15 

26 

CA1 

D12 

16 

25 

CRAY 

D13 

17 

24 

HDCS 

D14 

18 

23 

HDRQ 

D15 

19 

22 

FDCS 

Gnd 

20 

21 

FDRQ 


MEMORY MANAGEMENT UNIT (MMU) 



1 D4 18 RAS1 35 A15 52 DE 

2 D5 19 4Mhz Out 36 A14 53 DTACK* 

3 D6 20 8Mhz Out 37 A13 54 MAD5 

4 D7 21 CASH 38 A12 55 MAD4 

5 1 6Mhz IN 22 CAS1H 39 All 56 MAD3 

6 CASOH 23 WE* 40 A10 57 MAD2 

7 CASOL 24 DMA 41 A9 58 MAD1 

8 RASO 25 WDAT* 42 A8 59 MADO 

9 LATCH 26 UDS* 43 A7 60 MAD6 

10 VCCA 27 Gnd 44 +5v VCCB 61 Gnd 

11 A16 28 CMPCS* 45 A6 62 MAD7 

12 A17 29 DCYC* 46 A5 63 MAD 8 

13 A18 30 RDAT* 47 A4 64 MAD9 

14 A19 31 DEV* 48 A3 65 DO 

15 A20 32 AS* 49 A2 66 D1 

16 A21 33 RAM* 50 A1 67 D2 

17 LDS* 34 R/W* 51 VSYNC 68 D3 
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VIDEO CONTROLLER (SHIFTER) 


XTLO 

1 1 

40 

+5v 

32Mhz XTL1 

2 

39 

16Mhz elk 

DO 

3 

38 

CS 

D1 

4 

37 

DE 

D2 

5 

36 

A1 

D3 

6 

35 

A2 

D4 

7 

34 

A3 

D5 

8 

33 

A4 

D6 

9 

32 

A5 

D7 

10 

31 

R/W 

load 

11 

30 

Mono 

D8 

12 

29 

RO 

D9 

13 

28 

R1 

DIO 

14 

27 

R2 

Dll 

15 

26 

GO 

D12 

16 

25 

G1 

D13 

17 

24 

G2 

D14 

18 

23 

BO 

D15 

19 

22 

B1 

Gnd 

20 

21 

B2 


GENERAL HOUSEKEEPING (GLUE) 



26 

10 


27 



9 




1 




68 

43 



61 


44 

60 



1 

+5v Vcc 

18 

ROM3 

35 

Gnd 

52 

Gnd 

2 

A14 

19 

ROM2 

36 

BLANK* 

53 

SNDCS* 

3 

A15 

20 

ROM1 

37 

HSYNC 

54 

2Mhz out 

4 

A16 

21 

ROMO 

38 

VSYNC 

55 

R/W* 

5 

A17 

22 

RESET* 

39 

DE 

56 

A1 

6 

A18 

23 

RAM* 

40 

BR* 

57 

A2 

7 

A19 

24 

DMA* 

41 

BGACK* 

58 

A3 

8 

A20 

25 

DEV* 

42 

6850CS* 

59 

A4 

9 

A21 

26 

FCS* 

43 

500Khz out 60 

A5 

10 

A22 

27 

BGI* 

44 

MFPINT* 

61 

A6 

11 

A23 

28 

RDY 

45 

BGO* 

62 

A7 

12 

AS* 

29 

VPA* 

46 

LDS* 

63 

A8 

13 

FC2 

30 

BERR* 

47 

UDS* 

64 

A9 

14 

FC1 

31 

DTACK* 

48 

DO 

65 

A10 

15 

FCO 

32 

IPL1 * 

49 

D1 

66 

All 

16 

VMA* 

33 

IPL2* 

50 

IACK* 

67 

A12 

17 

ROM4 

34 

8Mhz In 

51 

MFPCS* 

68 

A13 
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Operating system overview 

The Atari ST operating system is in many ways functionally similar to 
MS-DOS, with extensions for handling a mouse, sound, the midi interface, an 
intelligent keyboard and joysticks. The source is based on a CP/M 68K related 
operating system referred to as the TOS (Tramiel Operating System). A graphics 
environment manager (GEM) provides additional single-user support for 
windows and communications via VDI and AES extensions, which support 
graphics and an applications environment. Program transportability is 
maintained by splitting the operating systems into machine independant (BDOS, 
VDI and AES) and machine dependant basic input/output utilities (BIOS and 
line- A routines). 

The ST programmer is given access to the VDI primitives via the line-A 
routines for much greater graphic application speed. 

The disk operating system (DOS) contains routines that provide access to the 
disc drives and support existing single user programs, file locking to ensure safe 
updating, unlock and read only facilities. Disk operation errors are trapped 
(where possible) and corrected. 

Machine/ 
dependant 
input/output 
routinesX 


General / 
operatingl 
system s\ 

Programmable segments of TOS 


BIOS 


LINE-A 

routines 




GEMDOS 


GEM VDI 

Basic 



Virtual 

disk 



device 

operating 



interfa 

system 


AFst 



The application environment (AES) multitasks using a timeslicing technique 
and supports a database file management system, real time data aquisition, 
communications and process control. 

The virtual device interface (VDI) allows the use of peripheral independant 
device drivers and provides a high degree of support for advanced user 
interfaces. 
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BASIC INPUT/OUTPUT SYSTEM (BIOS) 


The BIOS consists of all the machine dependent I/O routines of Digital 
Research's GEM and additionally provides access to the line-A routines for fast 
graphics. The I/O functions can be categorized as follows: 

GEM BIOS: 

System I/O: 

Console I/O: 

Disk I/O: 

STXBIOS: 

Port I/O: 

Screen I/O: 

Disk I/O: 

Keyboard I/O: 

Line-A routines: 

Pixel graphics 
Line graphics 
Sprite graphics 
Bit block transfer 
Mouse handler 


Parameter block initialization 
Data I/O & query 
Memory/ disk transfers 

Configure RS232, mouse, midi & sound port 
Get screen parameters 
Memory/ disk transfers 
Keyboard communications 


BASIC DISK OPERATING SYSTEM (GEMDOS) 


The disk operating systems permits the machine independent routines to 
access the disk drives and handle file management through the following 
functions: 


Set /get time and date 

Tree directory management 

File attribute management 

Create/ open/ close files and disk transfers. 

Current versions of GEMDOS impose a limit of 40 folders> 
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Virtual device interface (VDI) 


The VDI provides a set of graphic function calls that allow portability across 
physical hardware. Not all the standard VDI calls are implemented on all the 
operating systems available for the ST, the VDI tables Chapter 3 are annotated to 
show those that are missing from the various systems. 

Control I/O: Initialize graphics & set defaults. 

Graphics I/O: Primitives, lines, polygons, bars, arcs & pies. 

Attribute I/O: Set colour and style. 

Raster I/O: Bit block transfers, fill, font and cursor forms. 

Input I/O: Keyboard/ mouse interaction with console. 

Inquire I/O: Get attributes, resolution, style etc. 

Special I/O: Permits specialized functions to be performed. 

Application Environment Services (AES) 


The AES (application environment services) are a series of utilities that 
handle graphic based inputs to the user application. For example, instead of 
asking for INPUT - the screen displays graphically a menu of options which may 
include a clock, a file and perhaps a disk, these items being given a pictorial 
representation that is called genetically an 'Icon'. To select one, the user simply 
moves the cursor, which may look remarkably like an arrow, and places it on the 
required icon by moving the mouse and pressing a trigger button on the mouse. 

The AES routines are put into groups called libraries as follows: 


Application: 

Event: 

Menu: 

Object: 

Form: 

Graphic: 

Scrap: 

File Selector: 
Window: 
Resource: 
Shell: 

Application programs 


Provide access to AES routines. 

React to user inputs 

Translate defined text to menu format. 

Substitute graphic-icon for its label 
Handle text input automatically when needed. 
Primitive graphic functions. 

Management of cut and paste. 

Creation/display of user selected file. 

Handle windowing of queried input responses. 
Interface device dependant drivers to applications. 
Enable one program to call another. 


The desktop application is part of the operating system and is the base, user 
interface when other application programs are not running. It provides a 
calculator, alarm and clock; and through manipulation of icons via the mouse, 
disk directories, disk and file copy and deletions, disk formatting, as well as other 
activities such as communications, data output and window control 
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MEMORY ALLOCATIONS 


SFFFFFF 

SFF8800 

$FA0000 

$400000 

$100000 

$080000 

$000400 


$000000 


Memory 
mapped 
input/ 
output | 

ROM 
Area 


1 4M RAM 
max 

1024K 

RAM 


512K 

RAM 


OS BSS 
user RAI 
variables 




iSupervi 
RAM 
Ivariabled 


spr 


16777215 

16746596 

16384000 

4194304 

1 048576 


$FFFFFF 

$FFFC00 

$FFFA00 

$FFBA00 

$FF8800 

$FF8600 

$FF8400 

$FF8200 

$FF8000 


"MC~6850 

MK68901 

Blitter 

SOUND 

DMA/Disk 

Reserved 

Display 

Memory 


16777215 

16776192 

16775680 

16747108 

16746596 

16746084 

16745572 

16745060 

16744448 


MEMORY MAPPED I/O 
CONFIGURATION REGISTERS 


524288 

$FF0000 

192K 

16711680 


$FC0000 

system 

ROM 

16515072 

2048 ^ 

128K 

Supervisor 

access 

1024 only 

$FA0000 

cartridge 

ROM 

16384000 



ROM CONFIGURATION 
IN MEMORY 


References to the bottom 2K of memory and the I/O space are classed as 
supervisor references and attempted access from user mode will cause an error 
exception trap. 
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SYSTEM TABLES 


$800 


$400 


$200 


$100 


$0BC 

$0B8 

$0B4 

$0B0 


$08C 

$088 

$084 

$080 

$07C 

$078 

$074 

$070 

$06C 

$068 

$064 

$060 


$03C 


$02C 

$028 

$024 

$020 

$01C 

$018 

$014 

$010 

$00C 

$008 

$000 



— 




1024 




512 




256 





T raD #1 5 vector 

188 

TraD #14 vector 

184 

T raD #1 3 vector 

180 

TraD #12 vector 

176 


172 

TraD #3 vector 

140 

TraD #2 vector 

136 

TraD #1 vector 

132 

TraD #0 vector 

128 

Interrupt level 7 

124 

Interrupt level 6 

120 

Interrupt level 5 

116 

Interrupt level 4 

112 

InterruDt level 3 

108 

Interrupt level 2 

104 

InterruDt level 1 

100 

SDurious intrDt 

96 







Uninit int vector 

60 




48 

Emulation 1111 

44 

Emulation 1010 

40 

Trace 

36 

Privilege violation 

32 

Trap instruction 

28 

CHK instruction 

24 

Divide bv zero 

20 

llleaal instruction 

16 

Address error 

12 

Bus error 

8 

Initialise PC 


Reset init SSP 

0 


Operating system block storage segment 


System parameters 
and variables 


Reserved for OEMs 


Supervisor 

space 


MFP vectored interrupts 


XBIOS (ST extended BIOS) 
BIOS 


BDOS 

GEMDOS interface 

Non maskable interrupt 
68901 MFP 

Vertical blank sync 
Normal interrupt level 
Horizontal blank sync 


Unused vectors point to the 
system critical error handler 


Used by some AES functions 
Line-A routines entry 


The system variables are in 
the supervisor space and can 
be accessed only in supervisor 
mode 
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CONFIGURATION REGISTERS 


$FFFC0( 

1 ACIA 

Functions controlled 

16777215 Keyboard and MIDI I/O 

$FFFA0C 

, MFP 

1 67761 92 System checks, system interrupts 

$FF8800 

Blitter 

Sound 

16747108 

PSG 3 channel sound, noise, tone 
16746596 amplitude and envelope 

$FF8600 

DMA/Disk 

1 6746084 FI °PPy /hard disk > DMA 

$FF8400 

Reserved 

16745572 

$FF8200 

Display 

Video address, field rate, 
16745060 video made and palette 

$FF8000 

Memory 

16744448 Memor '' size 
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Resource management overview 

The pseudo multitasking kernal can support one primary application and 
one of a number of desk accessory programs. The main application may be GEM 
or DOS such as GEM desktop application or a word processing package etc. 


Screen 

environment 



Primary 


Desk 


Desk 


Desk 

application 


acc 1 


acc 2 


acc n 


A minimum space 
allocation of 128K 


A desk accessory is an application that does not take over the entire display 
screen, running in a specially designed window. The calculator is a typical 
accessory. 

Only one desk accessory program may be active at a time, and will only load 
if at least 128K of RAM is left for the primary application. 


CPU resources 

The dispatcher divides CPU time between primary applications and 
background processes. These jobs are put into lists; 'Ready for processing' and 
'Not ready 7 , and are serviced on a round robin schedule with the current process 
at the head of the list running. Not ready processes may be waiting for a key 
press, mouse movement or trigger, time lapse etc. 
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Graphics Concept Overview 

The Atari ST graphics is supported at a primitive level through the line- A 
routines and at a higher level through a limited version of the Digital Research 
graphic system extension (GSX), which is based on the ANSI virtual device 
interface (VDI). VDI provides a set of graphic primitives (GDOS) and a library of 
device drivers (GIOS) for the preparation of transportable software. The whole of 
GDOS and GIOS are not included in the ROM based ST operating system and 
there is no support for a small number of the VDI functions. These mainly cover 
lack of support for multiple fonts, the driving of 'non-standard' output devices 
and the use of 'normalised device coordinates. 

The VDI interface provides output primitives of lines, arcs, polygons etc. and 
input primitives to point symbolically, get co- ordinates of joystick/mouse or 
keyboard input etc. It also supports the control of multiple output devices using 
raster screens. 

The line-A routines give very fast access to the primitive pixel, line, sprite 
and bit block transfer graphic functions at the expense of portability 

RASTER COORDINATES are based on screen pixels. 

0,0 

’ r 1 


640,400 

GEM programs are portable but must take into account two possible problem 
areas: 

Screen aspect ratio: Different hardware systems and displays (screen, 
printer, plotter or another computer) may have different aspect ratios. Producing 
similar screen designs requires the programmer to scale the data sent to the 
display device using the aspect ratio returned from the open workstation call. 

Language implementations: Different language implementations of a 
program will require different length text strings to be fitted into windows. The 
inquire character cell width call in conjunction with the window size returned by 
the wind_get call will enable the programmer to determine the number of 
characters acceptable. 
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Alert and Dialog boxes have predetermined responses set up using the 
resource construction set and therefore do not present a language problem. 

The missing part of GDOS is available as part of the code supplied in Cu idin 
Digital Research products and may at a later date become more generally 
available for the ST (as 'AUTOXGDOS.PRG' file). On this premise, the details of 
the missing parts are given coupled to a rider that they are not available on the 
basic system. 

GEM usually provides two graphic coordinate systems to the programmer, 
raster and normalized. 

Raster is based on the computers screen resolution, in the case of the Atari ST 
600 x 400 pixels (monochrome). 

NDC (not implemented) is based on a notional screen of 32767 x 32767 points, 
the points being translated to the actual screen of the target system by one of the 
GIOS device drivers. The idea behind this is to write software independant of 
specific screen resolutions. 

NORMALIZED DEVICE COORDINATES are based on a screen of 
32767x32767 pixel dimensions. 

r 1 32767,32767 


0,0 


Graphic Coordinate Computation 


32767,32767 


Full NDC mapped to 
full RC space 


640,400 


0,0 U 
0,0 
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Overview of screens 


The Atari ST screen may be operated in three different resolution modes, the 
colours may be chosen from a palette of 512 colours: 

High: 640 x 400 pixel, black and white display 

Medium: 640 x 200 pixel, 4 colour display 

Low: 320 x 200 pixel, 16 colour display 

High Resolution 640 x 400 pixels 


Origin 



SINGLE 

PLANE 



Black border 


No colour but inverse video is 
available determined by the 
condition of bit zero of palette 
colour zero 


Medium Resolution 640 x 200 pixels 


Origin 



TWO 

PLANES 


Border is palette colour zero 


Only the first four lookup table 
entries are available. 


Low Resolution 320 x 200 pixels 
Origin 













FOUR 

PLANES 



16 word lookup table of 9 bits/entry 

3 red, 3 green and 3 blue on low 
nibble boundaries, giving 8x8x8 
possible colours (512). 


Border is palette colour zero 


It is not possible to change resolution while using GEM 
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Colour Palette Table 

Palette colour 



Physical to logical screen transposition 


High resolution mode 640 x 400 

PHYSICAL SCREEN 


1 

2 

3 

CD 

642 



pixels 


LI 6 117 1 


LOGICAL SCREEN 
bit 15 bit 0 


MSB word 1 LSBI MSB w6rd 2 LSB 


MSB word 41 LSB 


400 words 


Kl 


- 40 words - 


MSB word 16000 LSB 


Low memory 
word 1 


word 'Z 
word 0 


jiigh low 


word 1 5999 


word TBOUO 


Screen in 
memory 


Border always set black 


Bit zero of the colour 
palette provides inverse 
video 
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Medium resolution mode 640 x 200 

PHYSICAL SCREEN 


1 

2 

641 

642 


31 


8 I 9 


pixels 


LOGICAL SCREEN 
bit 15 bitO 


plane 

1 

2 

1 

2 


Low memory 


Plane 1 


MSB word 1 LSB I MSB word 3 LSB 


MSB word 2 LSB 

MSB wo 

'd 4 LSB 




1 

20C 

i words 




TMi 

>B word 16000 LSEI 


word 1 
word 2 


word 3 


high low 


word 15999 


word 1 6000 


Screen in 
memory 


15 13 


Border set by colour palette zero 
2 1 0 


Plane 1 word 
Plane 2 word 


Colours generated by interleaved bits of words 

Low resolution mode 320 x 200 

PHYSICAL SCREEN 


Plane 

Palette 

1 2 

colour 

0 0 

0 

0 1 

1 

1 0 

2 

1 1 

3 


m 

2 

C\J 

CO 

322 


8 I 9 


pixels 


LOGICAL SCREEN 

bit 15 bitO 

I MSB word 1 LSB 1 MSB word 5 LSB 


MSB word 2 LSB 


MSB word 6 LSB 


Plane 1 

Plane 2 


Colours generated by 
interleaved bits of the 
four planes. Plane 1 
provides the least 
significant bit in the 
palette table pointer 


MSB word 3 LSB I MSB word 7 LSB 


Plane 3 


0 


MSB word 4 LSB MSB wo 

rd 8 LSB 

20C 

words 



tm; 

>B word 16000 LSEI 


Border set by colour palette zero 
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Color generation 

A word from each plane is taken from the video display file and placed in the 
video shift register from where the bits are collectively used to index into the 
colour palette table. The colour code generated is supplied to a 3-bit digital to 
analogue convertor to produce the RGB signals. 


Logical bit-map Video display Video shift Colour palette 
planes memory register and 3-bit DAC’s 



In high resolution monochrome mode, the video shift register passes its data 
to the inverter and not the palette lookup table. 

Colour changing 

To prevent jitter when changing colors using the Hblank ($068) and Hsync 
($120) interrupt vectors, programmers should use the following procedure: 

1) Revector keyboard/MIDI interrupt to a routine that lowers the IPL to 5 
and then jumps through the original vector. 

2) During the critical section of screen, revector the system 200Hz clock 
interrupt vector to a routine that increments a counter and then RTEs. 

3) After the critical section, block interrupts (at IPL 6) and call a system clock 
handler that jumps through the interrupt vector with a fake SR and return 
address on the stack, the number of times indicated by the counter. 

Animation 

Animation is most easily achieved by switching alternately between two 
screens; one on display, the other being updated in the background. Initially 
write two identical screens and display one while modifying the other, swap the 
screens over and display the modified screen while updating the one previously 
on display. The technique will produce a very stable display with quite slow 
switching rates. 
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Sound concept overview 

Sound is generated via a Yamaha YM2149 programmable sound generator. 
The PSG contains three tone generators that produce the basic square wave tone 
frequencies for the A, B and C channels and a noise generator, that produces a 
frequency modulated pseudo random pulse width square wave, which may be 
combined with the tone generator outputs using the channel mixer. The output 
level can be fixed via the channel amplitude control using one of the three sixteen 
level D/ A converters or varied by using the output of the envelope generator, 
which may be used to amplitude modulate the output of each mixer. 

Sound control registers 

The frequency of each tone generator (30Hz to 125KHz) is obtained by 
counting-down the 12-bit value of the tone registers (the coarse register sets the 
upper 4 bits and the fine register sets the lower 8 bits, range 001 H to FFFH (1 to 
4095). The standard PSG format is to produce a lower note for a higher count 
whenever a register count-down is performed. 

The noise generator frequency is controlled by a 5-bit noise period register, 
value 01H to 1FH (1 to 31), producing a frequency range of 4Khz to 125Khz. 

The mixer control register is a multi-function register that mixes the noise 
channels (defined by bits 3 to 5) and the tone channels (defined by bits 0 to 2) in 
all possible combinations to the input/output ports (bit 6 I/O, bit 7 port A or B). 

The amplitude of a channel is controlled to one of sixteen fixed levels by the 
channel D/ A converter register (lower 4 bits of the register) and only by setting 
the register to zero can the channel be turned off. The fifth bit of the amplitude 
control register is set to select the variable level output defined by the envelope 
generator. 

The envelope generator comprises of three registers, two provide the 
frequency variation and the third the format of the envelope. The frequency is 
determined by counting down the 16-bit value of the coarse and fine envelope 
registers range 0001 H to FFFFH (1 to 65535). The shape and cyclic pattern of the 
envelope is defined by the lower 4 bits of the shape register (the amplitude 
register setting the level), the four bits provide for combinations of hold/cycle, 
reverse cycle on/off, ramp up/down and cycle hold pattern/reset to zero. 
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Parallel data I/O 

The I/O register in the PSG is not associated with sound production, it 
provides a register to transfer 8-bit parallel data to and from the CPU bus to the 
I/O port A, there is no affect on any of the PSG's other functions. 

Port A is controlled through functions 'ONGBIT' and 'OFFGBIT' (See page 
B.4 for bit functions and 3.12 for calls). 

Port B read /write is controlled through BIOS functions BCONOUT and 
BCONIN (See page 3.4 for calls) 

Data is written to a peripheral device from the bus using the following steps: 

Select enable register (mixer register) 

Set bit 6 to 'V (set I/O port A to output) 

Select I/O port A data store (I/O port A register) 

Write data to PSG (write data to I/O port A register) 

Once data has been loaded into the register, the data remains until further 
data is loaded, the system is reset, or 

the register is switched to input mode. 

Data is read from a peripheral device to the bus with the following steps: 

Select enable register (mixer register) 

Set bit 6 to '0' (set I/O port A to input) 

Select I/O port A data store (I/O port A register) 

Read data from PSG (read data in I/O port A register) 

The register follows signals applied to the port, only by reading will the data be 
transferred to the bus. 
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Sound configuration registers 


Access to the PSG should be in supervisor mode as the SR register is 
modified. The PSG registers are located for write at address ($FF8800-1 6746596) 
as follows: 


offset 


0 

$0 

Channel A fine tune 

(8 bit) 

1 

$1 

Channel A coarse tune 

(4 bit) 

2 

$2 

Channel B fine tune 

(8 bit) 

3 

$3 

Channel B coarse tune 

(4 bit) 

4 

$4 

Channel C fine tune 

(8 bit) 

5 

$5 

Channel C coarse tune 

(4 bit) 

6 

$6 

Noise generator control 

(5 bit) 

7 

$7 

Mixer control, I/O enable 

(8 bit) 

8 

$8 

Channel A amplitude 

(5 bit) 

9 

$9 

Channel B amplitude 

(5 bit) 

10 

$A 

Channel C amplitude 

(5 bit) 

11 

$B 

Envelope period fine tune 

(8 bit) 

12 

$C 

Envelope period coarse tune 

(8 bit) 

13 

$D 

Envelope shape 

(4 bit) 

14 

$E 

I/O port A 



Tone frequency calculations (registers 0 to 5) 

The tone frequency is in the range 30.5Hz to 125Khz and may be calculated from 
the formula: 

f= 2JUU 6 

16*(256 * CT + FT) 

where CT=coarse tone period 

FT=fine tone period 

Noise frequency calculations (register 6) 

The noise frequency is in the range 4Khz to 125Khz and may be calculated 
from the formula: . 

f= 2 * 10 6 
16 * Np 

where Np=noise period 
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The mixer control I/O enable 
(register 7) bit functions take 
the following format: 


BIB 

3 4 5 

6 7| 

mm 


l«Mil 

A B Q 


WM si 

If the bi 
the chan 

is zero 
nel is on 

Hffitli 


Envelope calculations 


The channel amplitude 
(registers 8-11) bits have 
the following function: 

I - I - I - I Ml x I xl xl xl 

M = 0 Fixed amplitude level 
0-low to 15-high (xxxx) 

M = 1 Amplitude determined 
by envelope shape 


Period 

The envelope period (registers 11 & 12) of the shape is based on the 16-bit 
register value: 

fe = . fclock 
256 * Ep 

where Ep ^envelope period 
fclock =i/p clock frequency 

Shape/cycle 

The envelope shape/cycle control (register 13) bit settings produce the 
following range of sound envelopes: 


Bits 

3 2 10 

Function 

Bits 

3 2 10 

Function 

0 0 x x 

\ 

10 11 

\r 

0 1 x x 


110 0 

AAAA/ZV 

10 0 0 

NMMWnN 

110 1 

A~ 

10 0 1 

\ 

1110 


10 10 


1111 

A 


Bit 0 = Hold/_cycle Bit 2 = Ramp up/_down 

Bit 1 = Reverse on/_off Bit 3 = Cycle hold/_reset zero 

1 bit set 
0 bit clear 
x don't care 
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GEM disk operating system GEMDOS 

Overview 

For those systems supplied with the operating system on disk; the system 
disk contains on the first two tracks, a cold start loader that loads the operating 
system image file (TOS,IMG) into high memory and then block loads it down 
into RAM memory at address $5000. 

The TOS image file contains both the GEM and Atari ST extended operating 
systems, including: 

BDOS Basic disk operating system Access functions to the file system 
BIOS Basic I/O system -Functions that interface peripheral device drivers 

The operating system is always in memory above $400 and all modules 
reside permanently in memory, even those of disk based systems (unless the 
power is removed). After TOS is loaded, the remaining contiguous address space 
is called the transient program area (TPA) where TOS loads executable 
(command) files. The command files (programs) should not access absolute 
addresses or default TOS variables but use the BIOS and GEMDOS function calls, 
except those system variables documented in Appendix A (upto address $04xx). 

Each transient program loaded into memory consists of the program 
segments (Text, Data and BSS), a user stack and a Base Page. The 256 byte Base 
Page contains the direct memory address (DMA) buffer, at base page offset $80; 
the buffer contains the command tail, typically the input typed to an application 
installed as a TOS Takes Parameters program. Before the loaded program takes 
control, the address of the transient programs base page and a return address are 
pushed onto the user stack, 4(A7) and (A7) respectively. 

Although the OS can only load one program; the transient program itself can 
load further programs using GEMDOS function $4B, but must specifically supply 
the base page and return address if they are required. 

A return from a transient program may be achieved by: 

An RTS as the last statement, returning via the return pushed onto the stac 
the load function. 

Execute warm boot by calling extended BDOS function 0. 

Type Control_C from the console during the execution of console 
output, printing a string or reading from the console buffer (functions 2, 9 and 10) 
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GEMDOS Memory model 

System 


Loaded 

transient 

program 


System 


The format of a command file is that of a header, two program segments (text 
and initialized data segments) and optionally a symbol table and relocation 
information. After the program is linked and loaded into memory, it contains 
additionally a zeroed uninitialized data (BSS) program segment and starts 
execution at the beginning of the text segment. 

Not all assemblers provide for an uninitialised data section within the source 
code, this results in executable GEM based program files on disk that are much 
larger than necessary. 

The operating system holds information on the data segments in a descriptor 
block (256 byte base page data structure) at the bottom of the TPA. The base page 
does not reside at a fixed address, its position is determined when it is created by 
the load a process function (GEMDOS function #$4B) and held in register DO.L. 

The base page contents are initialized by the GEMDOS load function: 

Base page format initialized by GEMDOS 

0 Base address of TPA 

4 End address of TPA + 1 

8 Base address of text (code) 

12 Length of text (code) 

16 Base address of initialised data 

20 Length of data 

24 Base address of BSS uninitialised data 
28 Length of BSS uninitialised data 



Low memory 0 


GEMDOS 

application 


High memory 
Command file 
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There are slight differences between small sections of the original CP/M 68K 
and GEMDOS base page formats as follows: 


CP/M 68K format 





$20 


32 

$24 


36 

$25 


37 

$38 


56 

$5C 


92 

$80 


128 


GEMDOS format 


Length of free memory after BSS 
Drive from which program loaded 
Reserved by BDOS 

2nd parsed FCB from command line \ Set 
1st parsed FCB from command line by 
Command tail and default DMA buffer/ OS 





$20 


32 

$24 


36 

$28 


40 

$2C 


44 

$80 


128 


DTA address pointer 
Parent's base page pointer 
Reserved 

Pointer to environmental string 
Command line image (typically the entry to a 
dialog box for a TIP application) 


File header format 


GEMDOS file header and program segments take the format: 





$00 


0 

$02 


2 

$06 


6 

$0A 


10 

$0E 


14 

$12 


18 

$16 


22 

$1 A 


26 

$1C 

28 


Data and BSS contiguous 601 AH 
Number of bytes in text segment 
Number of bytes in data segment 
Number of bytes in BSS 
Number of bytes in symbol table 
Reserved 
Reserved 
Reserved 

Beginning of text segment 


NOTE that 601AH is a BRA.S instruction that bypasses the file header data 
segment. The Atari OS does not support segmented files. 
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Symbol table 


The symbol table consists of fourteen bytes that specify a null padded 8 
character name, the type of symbol and the symbol value (address etc). 


hex 

Symbol type 

$100 

$200 

$400 

$800 

$1000 

$2000 

$4000 

$8000 

BSS 

Text relocatable 

Data 

External reference 
Equated register 
Global 
Equated 
Defined 


$00 

Ascn 


name 

$07 

null padded 

$08 

$09 

Type.W 

$0A 

Value. L~~ 

$0E 



Relocation table 


The linker optionally produces a relocatable executable file and places the 
relocation information in the GEM file header. 

GEMDOS header file 
$1 A 


$1 E 
$1 F 
$20 


Offset. L 


Offset 1 


Offset 2 


$00 


26 

30 

31 

32 


/ 


Byte 

sized 

offset 

data 


No more offsets 


Longword 



offset 

offset 1 

offset 2 


J 

iXt 1 

st 2 

3 

CL 

CO 

rd 


start 


Longword to relocate 
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If the offset byte is 1, then a multiple byte offset based on the following table 
is used to determine the actual offset. 

Offset Relocation data 

byte value 

$00 End of relocation data 

$01 Add 254 from current location and decode next byte 

$02....$FE Add byte value from current location 

Other odd numbers are not used (reserved) 

When the program is loaded into memory at a location other than where it 
was linked, BDOS computes an offset and adds the offset to the address of the 
relocation words in the text and or data segments. 

GEMDOS function $4B (75 decimal) loads or executes a program. 
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Atari ST file system 

GEM contains a fairly comprehensive sets of file manipulation facilities, they 
enable the programmer to write software that provides multiple access file 
sharing and file protection, periodic file updates and selective backups. The file 
facilities are: 


Code 

Dec 

Hex 

GEMDOS function 


60 

3C 

Create file 


61 

3D 

Open file 

Invoked by filling a 

62 

3E 

Close file 

parameter block with the 

63 

3F 

Read a file 

number of the function. 

64 

40 

Write a file 

the parameters and any 

65 

41 

Delete file 

other relevant data. 

66 

42 

Seek file pointer 


67 

43 

Get/ set attributes 

Returns are in DO.L 
Zero indicates o'k 

69 

45 

Duplicate file handle 

Where data is returned. 

70 

46 

Force file handle 

DO contains the address 
of the data return block 

78 

4E 

Search for first 


79 

4F 

Search for next 

GEM uses the stack as 

96 

56 

Rename file 

the parameter block. 

97 

57 

Get/set 

date/timestamp 
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Atari ST disk system 

The Atari ST 31/2" disk uses soft sectored disks of the following format: 


Bytes/sector 

512 


Sectors /track 

9 


Tracks /side 

80 


Sides /media 

1 

2 

Unformatted 

360K 

720K 


The GEM BIOS interfaces (Basic input/output systems) make the hardware 
dependent interface to the floppy disk drives. These communicate with the drives 
as follows: 

Select the drive, the side, the track and then the number of sectors from the track that 
will be read to a buffer or written from the buffer to the disk. 


GEMDOS is fairly basic in terms of disk operations but has extensions to 
handle tree type directories. 


Code 

Dec 

Hex 

GEMDOS function 

14 

0E 

Set default drive 

25 

19 

Get default drive 

54 

36 

Get drive free space 

57 

39 

Create a subdirectory 

58 

3A 

Delete a subdirectory 

59 

3B 

Set current directory 

71 

47 

Get current directory 


A file does not use consecutive disk sectors as there is insufficient time to 
identify, read and or write a record via software, and to locate a specific track via 
hardware. The record spacing (skew) is usually 6 sectors between adjacent file 
segments. 
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Atari ST BIOS comparisons 

The ST contains device dependant input/output utilities that handle the 
interface between the device independant routines and the hardware, the ST 
BIOS and GEM BIOS utilities are supplemented by the line-A primitives which 
provide rapid screen control. 

The GEM type BIOS handles the input/output to the peripheral devices: 
parallel port, RS232 port, console, midi interface and intelligent keyboard. There 
is also a basic disk read/ write to sector and a facility to check that the disk has 
not been removed or replaced. 

The ST extended BIOS also controls the input/output to the midi interface, 
intelligent keyboard, console and disk read/write, but additionally includes the 
control of a mouse, joysticks, sound and of the screen colours. 

The line-A routines are the VDI graphic primitives which are not program 
transportable and therefore included here, they enable control of the mouse and 
pixel-line-sprite-screen graphics. 


Interrupt handler overview 

The operating system provides the machine code programmer with access to 
the interrupt handler. 

Every 1 / 50th of a second control is transferred from the operating system to 
a routine at the address designated in the system variables at $68 (104 decimal), 
the system interrupt handler (vertical blank interrupts). The handler provides a 
timing facility, sets the screen parameters and current device driver installation 
and entry points. 
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System Initialisation 


The ST in general follows a predefined initialization sequence on power-up, 
with variations for the different operating systems, typically: 


System reset 

ssp— > $60xxxxxx 

pc— > S00FC0020 

move.w #$2700,SR 
reset 


The supervisor stack pointer (SSP) and 
program counter (PC) are set from $0 
and $4 respectively, the SSP is 
garbage until the system is sized. The 
Interrupt priority level (IPL) is set 
to seven and a hardware reset executed 


cmpi.l #$FA52235F,$FA0000 A check is made for a diagnostic 

cartridge, which if present will cause 
bne cmpi_nxt a return address to be set in A6 and 

lea $8(PC),A6 execution of the diagnostic routines 

jmp $FA0004 commenced. 


cmpi.l 

#$31415926, $426 

bne 

psgset 

moved 

$42A,D0 

tst.b 

$42A 

bne 

psgset 

btst 

#$0,D0 

bne 

psgset 

movea.l 

DO, AO 

lea 

$4(PC),A6 

jmp 

(AO) 

lea 

$FFFF8800,A0 

move.b 

#$7,(A0) 

move.b 

#$C0,$2(A0) 

move.b 

#$E,(A0) 

move.b 

#$7,$2(A0) 

move.b 

#$0,$FFFF820A 

lea 

$FFFF8240,A1 

move.w 

#$F,D0 

lea 

$28A(PC),A0 

move.w 

(A0)+,(A1)+ 

dbf 

D0,loop 


A check is made to see if memory has 
previously been sized (warmstart). If 
not jump past memory sizing routine. 

If this is a soft reset, the bailout 
vector may be valid. First check that 
the MSB is zero, secondly that the 
vector is to an even address, if not, 
jump past the reset handler. 

Set AO to point to the reset handler, 
set A6 to the return address and 
jump to reset handler. 

Set AO to PSG configuration register 
base and set port A & port B to output, 
activate general purpose output and 
through output port A deselect the 
disks. 

Set sync mode to external 50/60Hz and 
A1 to base of pallette table. 

Set up a count in DO to shift the 
default hardware palette colors to 
AO which points to the default color 
table. 


2.28 




Operating System Overview 


move.l 

move.l 

move.l 

lea 


move.l 

move.l 

move.l 

move.l 

move.l 

move.l 

move.l 

move.l 

move.l 

move.l 

suba.l 

suba.l 

move.w 

lsl.w 

move.w 

bsr 

and.l 

btst 

beq 

ddq.w 

movea.l 

suba.l 

move.l 

move.l 

rts 

move.l 

subq 

clr.b 

dbf 


#$752019F3,$420 

#$237698AA,$43A 

#$8900,$432(A5) 

$D50,A7 


rte,$14 

#$FC0324,$70(A5) 

rte,$68(A5) 

rte,$88(A5) 

#$FC03C0,$B4(A5) 

#$FC03BA,$B8(A5) 

rts, $400(A5) 

#$FC03B6,$404(A5) 

rts,$408(A5) 

#$550,$4A2(A5) 

A5,A5 


Size both memory banks and perform a 
memory test. Set 'memory sized' and 
'memory tested' flags in the system 
variables table. Set up screen, vblank 
queue entries, BIOS entry point and 
supervisor stack. 

Run type '0' cartridge applications. 
Point A3 and A4 at RTE and RTS resply 
Test diagnostic cartridge. 

Initialise exception vectors to 
terminate process handler except for 
divide by zero which is RTE'd. 

Set vblank handler entry address. 

Kill hblank handler entry address. 
Initially empty trap#2 handler. 

Set up trap#13 handler address. 

Set up trap#14 handler address. 

Default timer tick vector to RTS. 

Set up the critical error handler 
and default the terminate vector. 

Set up BIOS register save area pntr 
Zero page pointer. 


A5,A5 

$454(A5),D0 

#2,D0 

D0,D1 

make_spc 

#$FFFF,D0 

#$0,D0 

jumpl 

#$1,D0 

$436,A0 

D0,A0 

A0,$436 

A0,D0 


Intialize vblank vector list. 

8 nvbls into DO 
multiply by four to 
create queue length in Dl. 
Routine to create a space of 
8 longwords in high memory. 
\make 
I address 
/even 

current memory top 
'come on down' 
reset memory top 
and put in DO 


A0,$456(A5) 

#$1,D1 

(A0)+ 

Dl,clr_byte 


vblqueue start address 
I zero the queue 
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Initialize screen resolution. 

move.w #$F8FF,SR Enable all interrupts except Hblank 

by setting IPL to 3. 

Run type '1' cartridge applications 
Initialize GEMDOS- set up a DOS 
disk buffer chain & memory manager. 
Run type '3' cartridge applications 
Attempt to boot from floppy and 
execute if successful, if not poll 
devices on DMA bus for logical boot 
sector zero, execute if successful, 
(checksum $1234). Any 'returns' 
continue polling the devices in sequence. 
Turn on the cursor. 

Execute file COMMAND.PRG? otherwise 
construct a default environment and 
execute AES. 

Initiate a RESET on a return. 
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Cartridge Software 

There are two types of cartridge which may be plugged into the ST; 
diagnostic and program cartridges. The cartridge program header format is as 
follows: 



Only the first header contains a flag which denotes the 
presence of a cartridge. 

Flag: #$FA52255F ^diagnostics 

#$ABCDEF42=program/data 
Pointer to next application header, a null indicates no 
additional applications 

Pointer to application initialisation code, if zero there is no 
initialisation code. The longword high byte is unused in the 
24-bit address and starts applications as follows: 
bit 0-set, run before interrupt vectors & memory initialised 
bit 1-set, run before GEMDOS initialised 
bit 2-unused 

bit 3-set, run before disk boot 
bit 4-unused 

bit 5-set, application is a desk accessory 

bit 6-set, not a GEM application (no AES calls) 

bit 7-set, needs command line parameters before execution 

Pointer to application entry point 

Time \ 

DOS format time and date stamps 

Date / 

The size of the application BSS segment allocation. The OS 
must allocate the BSS before invoking any run code. Set to 
zero if not applicable. 

The ASCII name (max 12 characters) terminated by a zero 
nnnnnnnn.eee 


Diagnostic cartridge: The ST hardware will not be initialised and a return 
address is held in A6, the stack pointer is trashed. The cartridge software is 
responsible for sizing memory and setting the hardware registers as required. 

Cartridge software: Application headers are strung together in a linked list, 
so there may be any number of applications on one cartridge. 
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Boot Sectors 

To write software that will auto run from disk, the programmer must 
produce a boot sector that contains a loader program which transfers the 
program from disk to memory before bringing up GEM. 

The boot sector follows IBM PC format and contains: 

The volume serial number 

24 bit number generated when the media is formatted 

BIOS parameter block (BPB) 

Sector size in bytes 

Number of sectors /cluster 

Cluster size in bytes 

Length of root directory in sectors 

Size of a File Allocation Table (FAT-in sectors) 

Sector# of start of second FAT 
Sector# of first data sector 
Number of data clusters on disk 
Flags 

Optional boot code and boot parameters 

During initialization the boot sector is loaded into a buffer and the executable 
boot sector code tested for a word checksum of #$1234. If satisfactory a 
subroutine jump is made to the beginning of the position- independent code in 
the buffer. 

When a 'get BIOS parameter block' call is made, the BIOS reads the boot 
sector (normally created when the volume is formatted), and returns an error 
indication if any critical parameter fields are zero. 

The 24-bit volume serial number, written when the media is formatted, is 
used to determine whether or not a disk has been changed. 

The 'protobt' extended BIOS call (dec 18) is used to create the boot sector (pg 
3.8), which is written to track_0 side_0 sector_l. 
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BIOS boot parameter block 

Normally written when the volume is formatted. 





$00 

bra.s 

0 

$02 

oem_space 

2 

$08 

Vol serial# 
#$000000 

8 

$0B 

BPS 

#$00 #$02 

11 

$0D 

SPC 

#$02 

13 

$0E 

RES 

#$01 #$00 

14 

$10 

NFATS 

#$02 

16 

$11 

NDIRS 
#$70 #$00 

17 

$13 

NSECTS 
#$D0 #$02 

19 

$15 

MEDIA 

#$F8 

21 

$16 

SPF 

#$05 #$00 

22 

$18 

SPT 

#$09 #$00 

24 

$1 A 

NSIDES 
#$01 #$00 

26 

$1C 

NHID 

#$00 #$00 

28 

69 

L 

m 

boot code 

30 

$1 FE 

last word 

510 

$200 


512 


Branch to boot code 

Space reserved tor OEMs use 

24-bit volume serial number. 

(used to determine disk changes) 

Number of bytes/sector 

Number of sectors/cluster 

Number of reserved sectors 

(at start of media including boot) 
Number of file allocation tables on media 


Number of directory entries 

Number of sectors on media 

(including reserved) 

Media descriptor 

(not used by ST) 

Number of sectors/FAT 


Number of sectors/track 
Number of sides on media 


Number of hidden sectors 

(not used) 

Start of code, if any 
Checksum 


Note: Word storage is low byte at the low address (even) as per Intel 8088 format 
and not the usual 68000 mode. 


The BIOS parameter block is compatible with MS-DOS versions of the BPB, but 
will only read and write sectors written by another WD1772A disk controller. 
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Boot loader 


The boot loader resides in the boot sector and is used during system 
initialization to load an image file or a contiguous set of sectors; it is also used to 
load GEM from disk on early ST models. The format of the loader is: 


$00 

boot sector 

$1 E 

execfla 

$20 

Idmode 

$22 

ssect 

$24 

sectcnt 

$26 

Idaddr 

$2A 

fatbuf 

$2E 

fname 

$39 

reserved 

$3A 

boot code 


0 

30 

32 

34 

36 

38 

42 

46 

57 

58 


The standard BIOS parameter block 

The word copied to ’cmdjoad’ flag 

If lmode=0 load file 

If ImodeoO load from here 

If ImodeoO load ’sectcnt’ sectors 

Load address of file or sectors 

Address for FAT and DIR sectors 

Filename: 8 Character name. 3 Character extension 

(valid if 7 mode ’ is zero) 

Reserved 

The executable code 


Some software tools require the six bytes reserved for OEMs at offset $2 to 
contain the ASCII text 'loader'. 

The loader can load any file from disk regardless of where it appears in the 
directory or whether it has the form of contiguous sectors or not. 

An image file contains no header or relocation information and is an exact 
copy of the program to be executed. 
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Boot ROM 

The initialization of the system from the boot ROM follows the predefined 
pattern of a RESET with some system variables installed and pretty color screen 
graphics to keep the operator from getting bored. 

The boot directory and second FAT buffer are read into memory starting at 
membot. TOS.IMG is loaded starting at $40000 and an error code produced if the 
file is not found. The memory $10000 to $20000 is used for screen buffers and 
should not be used initially for any code or data. 

The first ST's sold contained a small 32K boot ROM that loaded the operating 
system from disk. The boot ROM contains a small sub-set of the BIOS, just 
sufficient to read an 80 track, BPB floppy disk boot sector from either drive into 
memory and then execute it. 

Trap 13 GEM BIOS functions implemented 

code function 


4 rwabs Read/write sectors (read only) 

7 getbpb Get BIOS parameter block 

Trap 14 extended functions implemented 

code function 


1 ssbrk Reserve x bytes from top of memory 

8 floprd Read sectors from floppy disk 

All other BIOS facilities are not loaded into the system until a later stage. The 
first 100 bytes of disk TOS relocate TOS.IMG at $5000 from where it takes control. 

The first TOS implementation uses the following disk parameters: 


80 track, single sided BIOS parameter block 


Bytes /sector 

512 

#sides/media 

1 

Sectors /cluster 

2 

#hiddensectocrs 

0 

Reserved sectors 

1 

Load address 

$40000 

# of FATs 

2 

FAT/ directory buffer 

$8000 

# of root dir entries 

7 

Volume serial number 

0 

# of sectors on media 

720 

Media descriptor byte 

F8H 

# sectors /FAT 

5 

Filename 

TOS.IIv 

# sectors /track 

9 
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Atari ST peripheral device 
communications 

Communications overview 

The ST supports serial and parallel communications through dedicated 
RS232 and parallel ports, and permits two further communicaton channels to be 
opened through the MIDI and DMA ports. 

The serial RS232 communication port accomodates hardware data control 
based on the PSG I/O port A, RTS and DTR outputs, and the MFP MK68901, 
CTS, DCD and RI inputs, and Xon/Xoff software data protocol at transmit and 
receive baud rates in the range 50 to 19200 baud. The port is generally used to 
interface with a printer, modem or another computer. The MFP is located at 
$FFFA00 (16775680) and the $PSG at $FF8814 (16746610). 

The general purpose parallel port interface provides bi-directional 8 bit 
communications for printer operation. The port is based on the MFP MK68901 
(busy control), the PSG I/O port A bit 5 (strobe control) and the PSG I/O port B 
(data transfer). The control is limited to a busy signal, acknowledge is not 
supported and data transfer is at a typical rate of 4000 bytes /s. 

The MIDI interface provides an asynchronous, current loop, serial data (one 
start bit, eight data bits and one stop bit) communications channel at 31.25Kbaud. 
The MC6850 port controller may be reconfigured for most forms of RS232 
interface via the control/ status register situated at address $FFFC04 (16776196). 

The intelligent keyboard interface is also controlled by an MC6850 ACIA, but 
there is no external access provided to the port, which is of limited use other than 
accessing the ikbd command set; for reading and or writing to the clock, joysticks, 
mouse and perhaps reconfiguring the keyboard. The transfer rate is fixed at 
7812.5 baud. 

The floppy disk interface is based on the Western Digital WD1772A disk 
controller and is limited to supporting two drives. 

The DMA interface is provided by a ULA device, access is through the 
control /status configuration registers at $FF8600 (16746084) et seq. The DMA or 
Hard disk port uses an Atari version of the SCSI interface and can support a 
maximum of 8 peripheral devices. Theoretically data may pass either way 
through the interface so it should be possible to use it for high speed networking, 
remembering that the DMA controller also supports the Floppy Disk Controller. 
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RS232 interface 


General 

Data is transmitted and received via an RS232 interface as a sequence of ones 
and zeroes (bits) along a three wire link, one wire being ground, one for 
transmitted data and the other for the received data. Information is sent as 
'characters' and each character is prefixed by a start bit (a one) and terminated 
with either one or two stop bits (zeroes). Providing the sending and receiving 
devices are set to the same speed (baud), then the stop and start bits act as a 
timing signal to each 'character' sent. Occassionally error detection is 
incorporated in the form of a parity bit. If the count of ones in the character is 
even, then the eighth bit is set to a one (even parity), an alternative process is odd 
parity where if the one count is odd, the eighth bit is set to a one. Personal 
computers work without parity which is used in general as a warning of data 
errors in the transmission. Providing the transmitting and receiving station agree 
on the protocol used, then communications will be reasonably straight forward !!! 

The port is reconfigured using the sequence: 

a) Save current MK68901 register contents 

b) Disable Rx and Tx enable bits 

c) Set flow control mode 

d) Set baud rate 

e) Set RS232 registers 

f) Re-enable Rx and Tx enable bits 

The extended BIOS call #$0F (15) enables selective reconfiguration of the 
RS232 port according to a block of parameters pushed onto the stack: 


move.w 

sync_char,-(SP) 

* Pushing 

\ 

move.w 

tx_status,-(SP) 

* -1 

1 (page 

move.w 

rx_status,-(SP) 

* leaves 

1 3.10) 

move.w 

usrt_cntl,-(SP) 

* parameter 

1 

move.w 

flow_cntl,-(SP) 

* unchanged 

/ 

move.w 

baud rate,-(SP) 

* Set timer D 


move.w 

#15,-(SP) 

* push RS232 config 

trap 

#14 

* call function 


add.w 

#14,SP 

* tidy stack, jump 7 words 

tst.w 

DO 

* test for error 


rts 


* 



Data is passed through the interface using the extended BDOS calls to the 
auxiliary device (RS232 port). Only the 'New TOS' supports RTS/CTS 
handshaking. 
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Parallel port interface 

General 

Data is transmitted and received via a parallel port interface in blocks of 8 
(sometimes 7) data bits, set either as ones or zeroes to form a character byte. The 
character is 'framed' by a strobe signal enabling the receiving device to read the 
character transmitted, which may be printed immediately or saved in a buffer for 
subsequent printing. At some stage the printer will not be able to accept further 
input and will send a 'busy 7 signal to stop the transmitter from sending 
additional data. The acknowledge signal is sometimes used to indicate that the 
printer is no longer busy, occasionally this signal line is omitted and the busy line 
also provides the 'not busy' signal. 

Data is passed to and from the interface using the following procedures: 

Write data 

a) Check the busy line for high 

If line low, monitor until high 
or time out set CPU DO register to 0 

When high 

b) Set PSG I/O B port to output, use IPL 7 

c) Place data into the PSG's B output register 15 

d) Switch strobe line on. Port A bit 5 

e) Switch strobe line off, set CPU DO register to -1 

Read data 

a) Set PSG I/O B port to input 

b) Switch strobe line off 

c) Check busy line for high loop till high 

d) Switch strobe on 

e) Get data from PSG's B output register 

As the status register is affected, the above procedures should be performed 
in supervisor mode. 
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MIDI interface 


General 

The MIDI (musical instument digital interface) sequential circuits provide for 
integrated operation of music synthesizers, sequencers, drum boxes etc. which 
have the MIDI interface. The ST operates as a data store for a large number of 
notes /voices which may be sent to different instruments (channels), and played 
together in sequence and time as music. The data may be 'recorded' from a tune 
previously played, edited and/or synthesized by entering new data in step- 
time-note format into the store for later retrieval. 


The MIDI bus provides 16 channels in one of three networking modes. 
OMNI, the default where all units are addressed together and transmit and 
receive on all channels. POLY where all the units are individually addressed and 
receive on one channel only, data assigned to non-existant channels is ignored. 
MONO where the voice of each unit is addressed seperately, providing different 
channels for individual voices within one synthesizer. 


The information transmitted is priortised and sent as bytes, the most 
significant bit signifying either status (1) or data (0). The priority order is: 


System reset 
System exclusive 
Sequential circuits 
System real time 
System common 
Channel 


Set defaults 

Manufacturers unique data 
Roland, Yamaha etc. 
Synchronization 
Broadcast 

Note selection, prog data etc. 


The MIDI port supports the optional through port which merely provides the 
MIDI in signals at the MIDI out port. 


The MIDI interface operate in RS232 current loop mode at 31.25K baud. It 
may be reconfigured by resetting the control/status registers. 

The Atari ST's extended BIOS enables the programmer to reconfigure the 
MIDI port. 
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MIDI control/status register functions 

Controlregister functions (write only) $FFFC04 


Divide 
Bit selec 
0 1 


Bit 


Data format 


Bit RTS format Bit 


2 3 4 #bit Parity Stod 5 6 Tx on/of f 7 


Interrupt 

enable 


0 0 by 1 
0 1 by 16} 
10 by 64 


0 0 0 
0 0 1 
0 1 0 
0 1 1 
1 1 mast€'ri 0 0 


reset 


1 0 1 
1 1 0 
1 1 1 


7 even 2 
7 odd 2 
7 even 1 

7 odd 1 

8 - 2 
8 - 1 

8 even 1 
8 odd 1 


0 0 off RTS- 

0 1 on low 

1 0 off RTS- 

high 

1 1 off RTS- 
low 

Tx break level 
on Tx data o/p 


Interrupts 
enabled by 
bit 7 = 1 . 

Rx data 
register full, 
Overrun, 
DCD low to 
high step. 


Status register functions (read only) $FFFC06 

Bit Name and function 


0 Rx data register full 

Rx data in register ready for CPU read 

1 Tx data register empty 

Transmitted data sent, load with next character to transmit 

2 Data carrier detect 

Indicates modem state, carrier present 

3 Clear to send 

Indicates modem state, Master reset - no change. 

4 Frame error 

Character synchronisation error 

5 Rx over-run 

Characters have been lost from stream 

6 Parity error 

Only active if parity selected 

7 Interrupt request 

Read received data register or write to transmit data register. 
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Intelligent keyboard interface (IKBD) 

The intelligent keyboard functions through a MC6850 ACIA device whose 
control/status register is located at address $FFFC00 (16776192), and functions 
like the MIDI interface. There is no external access to this port so there is little 
point in reconfiguring, but it can be used to transmit and receive data or 
commands from the keyboard, mouse, joystick and clock using the following 
facilities: 


Keyboard 

Return keycodes 


Mouse 

Set mouse button action (keys, on press /on release) 
Set mouse position relative (default) 

Set threshold level per 'click' 

Set mouse position absolute 
Set scale ('clicks' per movement) 

Read/ write mouse position 
Set mouse to simulate cursor motion codes 
Set Y origin top/bottom 
Disable/pause/resume mouse operation 


Joystick 

Enable joystick (default) 

Disable, act on request only 
Interrogate joystick 

Set monitoring (serial line, joystick and clock) 
(serial line, button 1 and clock) 
Set keycode mode (variable 'click' rate) 

Disable joystick 
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Clock 

Set date and time 
Read date and time 

Program control 

Load data into ikbd memory 
Read data from ikbd memory 
Execute ikbd program 


A status inquiry command returns a null padded 8-byte packet detailing the 
current mode and parameters of a specific function, the packet may be stored and 
later used to restore the status of the keyboard by modifying the header byte and 
returning the data as a command. 

The keyboard scancodes do not maintain complete compatibility with IBM 
PC key scancodes. Appendix D.6 provides the major differences due to the non- 
availability of certain keys on the ST keyboard. The additional ST keys are 
mapped into unused CTL_ and ALT_ function scancodes. 

To detect ALT_ and CTL_ function key combinations, execute a BDOS or 
BIOS 'getchar' call followed by a BIOS 'kbshft' call (#$0B). 
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Floppy disk interface 

The floppy disk interface is based on an on-board Western Digital WD1772A 
disk controller and can support a maximum of two drives. 

The floppy disk read/iorite sequence of events is: 

a) select floppy drive 0 or 1 (PSG I/O port A) 

b) select floppy side 0 or 1 (PSG I/O port A) 

c) load DMA base address and counter register 

d) toggle read/ write to clear status (DMA mode control reg) 

e) select DMA read or write (DMA mode control register) 

f) select DMA sector count register (DMA mode control reg) 

g) select FDC internal command reg (DMA mode control reg) 
n) issue FDC read or write command (Disk controller reg) 

i) DMA active until sector count zero (DMA status reg) 

do NOT poll during DMA active. 

j) issue FDC interrupt command after sector data transfers, 

except at track boundaries (Disk Ctrl reg) 

k) Check MFP bit 5 ($FFFA01) for interrupt 

l) check DMA error status, non destructive (DMA stat reg) 

The DMA configuration registers are at the base address $FF8600 (16746084) 
and the following offsets: 

4 $4 Disk controller data access 

6 $6 DMA read_mode control, writeJFIFO 

9 $9 DMA base high \ set last 

11 $B DMA base medium I 

13 $D DMA base low / set first 

The PSG configuration registers are at base address SFF8800 (16746596) and 
the following offset: 

2 $2 PSG write port 

Bit 0 floppy side 
Bit 1 floppy drive 0 
Bit 2 floppy drive 1 

There is no hardware support for sensing disk removal, therefore this facility 
must be performed in software. 
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Formatting a floppy disk 


The following procedure illustrates the technique used in formatting a floppy 
disk: 


flopfmt $A 


Sides: lor 2 Sectors/track: 9 Tracks: 80 
No interleave and the first two tracks zeroed (to 0 FAT and 
directory sectors), either sector bad and the media is unusable 


protobt $12 


flopwr $9 


Use disk type parameter 2 or 3 
Serial number parameter, random or #$1000000 
Execute flag usually zero, non zero if it contains loader code 
etc. that is to execute when the disk is booted. 

Write boot sector (prototyped in buffer to track 0, side 0, 
sector 1 of disk 
Do not use Ywabs’ call 


XBIOS calls 

The WD1772 'write track' codes used to format a track are: 

Double density format: issue a write track command and load the following 
values into the data register. There is a data request for every byte written. 


ID field 


#bytes| 

data 


60 


12 

6#$od 


3 

#$F5 


ID 
#$F£ 


Trckl 
# 


0-$4F 


Side! 
# 


Sect 

# 


Len 

# 


0-1 


1-9 


55 


CRQCRC 
2 


#bytes] 

data 


22 | 12 
l#$4B#$00l 


ID 


512 


CRQCRC 40 


1 


l#SF5l# $FB datal 
Data field 

length = #512 bytes/sector (usually 2) 


2 i#$4E 


T4QT 
#$4B 
End of 
track 


CRC’s written $F7 

Note that early versions of TOS do not report CRC errors in all cases causing 
reduced reliability of the disk system. 
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WD1772 DMA channel interface 


The WD1772 is interfaced through the DMA channel via the following 
procedure: 

To initialize the WD1772: 


move.w #$190,$FF8606 
move.w #$90,$FF8606 
move.b #xx,dmalow 
move.b #xx,dmamid 
move.b #xx / dmahigh 


Clear the fifo by toggling r/ w 
and leave in the write state. 

Set up dma address pointer in 
low to high order 

SFF860D, $FF860B & $FF8609 resply 


The following addresses are used by the WD1772 

$80 128 command /status register 

$82 130 track register 

$84 132 sector register 

$86 134 data register 

To address the WD1772: 


move.w #$yy,$FF8606 The FDC rquires two writes to 

move.w #$zz,D7 access the registers, the first 

delay write selects the FDC register 

rts and the second write modifies 

the register 

To transfer from memory to floppy the values must be ORed with #$100 and 
#$FF written to $43E to prevent TOS from changing the value in address $FF8606. 
When the operation is complete the byte in $43E, the floppy lock variable, must 
immediately be zeroed. 

To seek to a track: 

move.w #$86,$FF8606 
move.w #$4F,$FF8604 
move.w #$80,$FF8606 
delay 

move.w #$17,$FF8604 


Select the data register 
Write seek track ($4F last track) 

Select command register 
Wait for drives 

Seek with verify (pg 1.23 Type 1 command) 
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The FDC will generate an interrupt when the seek is finished, it can be polled 
at $FFFA01 where bit 5 is zeroed. Errors are read from $FF8604, the read clearing 
the interrupt bit. 

To transfer data: 

move.b #$xx,dma set up dma address, clear fifo 

move.w #$190,$FF8606 

move.w #$1,$FF8604 512byte size limit of transfer write sector# (1.. 9) 

write track# (#$00. #$27) use #$A6 

write track# (#$28.#$4F) use #$A4 

read track#, use #$84 

Do not use read/write multiple sector commands as they require a force 
interrupt command which is slower than re-executing a read or write. 

To format a track 

write track# (#$00,#$27) use #$F6 

write track# (#$28,#$4F) use #$F4 

Write data to the drive beginning and ending with the index pulse. It takes 
about #$1 A00 bytes to fill a drive running at 3%. 


The existing format command produces 9 sectors per track. 

Do not change the id-field, the fourth byte is used to count the number of 
bytes to transfer, and to locate the CRC data field. It may produce 
incompatibilities with TOS if changed. 

To write an entire track: 

The entire track can be written as one long sector and then read back, without 
any error checking, using the read track command if the following format is used: 

Index pulse followed by 

#$00 a minimum of 12 bytes for lock-on 
#$F5 3 bytes for synchronization 
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DMA interface 

There is only one direct memory access (DMA) channel which is shared by 
both low and high speed 8 bit device controllers. The configuration registers hold 
the 3 register MMU base address of the DMA operation which is performed 
through a 32 bit FIFO programmed by the DMA mode control register. 

The hard disk read/write sequence of events is: 

a) load DMA base address 

b) toggle read/write to clear status (DMA mode Ctrl reg) 

c) select DMA read or write (DMA mode control register) 

d) select DMA sector count register (DMA mode cntrol reg) 

e) load DMA sector count register (DMA mode trigger) 

f) select HDC internal command reg (DMA mode control reg) 

g) issue FIDO read or write command (Disk controller reg) 

1st cmd AO set to 0, set to 1 for remaining commands 
Each byte command is acknowledged with an interrupt 
After last cmd byte set hard disk sector count bit 1 

h) DMA active until sector count zero (DMA status reg) 

do NOT poll during DMA active. 

i) check DMA error status, non destructive (DMA stat reg) 

j) check HDC status byte and if necessary perform an ECC 

correction following a verify track or read sector command. 

The DMA configuration registers are at the base address $FF8600 (16746084) 
and the following offsets: 

4 $4 Disk controller data access 

6 $6 DMA read_mode control, write_FIFO 

9 $9 DMA base high 

11 $B DMA base medium 

13 $D DMA base low 

The DMA registers are used to perform the floppy disk data transfers but 
may also be used for hard disk and other high speed data interfaces, bearing in 
mind the restriction of one DMA operation at a time. 

Any modification of the DMA base address or counter register requires that 
they be set in low-mid-high order. 
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DMA bus boot code 


The following code, which is typical of the ST's BIOS, attempts to load boot 
sectors from devices on the DMA bus. The code shows typically how the DMA 
bus is used and provides the timeout and the command characteristics expected 
from bootable DMA bus devices. 


gpip 

equ 

$FFFFFA01 

*.B 

68901 input register 

dskctl 

equ 

$FFFF8604 

*.W 

controller data access 

fifo 

equ 

$FFFF8606 

*.w 

DMA mode control 

dmahigh 

equ 

$FFFF8609 

*.B 

DMA base high 

dmamid 

equ 

$FFFF860B 

*.B 

DMA base mid 

dm alow 

equ 

$FFFF860D 

*.B 

DMA base low 

flock 

equ 

$43E 

*,W 

DMA chip lock variable 

dskbuf 

equ 

$4C6 

*.L 

IK disk buffer 

Hz_200 

equ 

$4BA 

*.L 

200 Hz counter 

bootmg 

equ 

#$1234 

*.W 

boot checksum 


Try to boot from DMA device 

dmaboot moveq #0,D7 

dmb_l bsr dmaread 

bne dmb_2 

move.l dskbuf,A0 

move.w #$00FF,D1 

moveq #0,D0 

dmb_3 add.w (A0)+,D0 

dbra Dl,dmb_3 

cmp.w #bootmg,D0 

bne dmb_2 

move.l dskbuf,A0 

jsr (AO) 

dmb_2 add.b #$20,D7 

bne dmb_l 

rts 

Try to read DMA bus device boot sector 

dmaread lea fifo,A6 * DMA control register 

lea dskctl,A5 * DMA data register 

st flock * DMA lock against vblank 

move.l dskbuf,-(SP) * 

move.b 3(SP),dmalow * set up DMA pointer 

move.b 2(SP),dmamid * 

move.b l(SP),dmahigh * 


* # devices to try (eight) 

* try to read boot sector 

* failed — next device 

* disk buffer pointer in AO 

* checksum #$100 words 

* initialize checksum 

* add a word 

* until #$100 counted 

* Is it a boot sector 

* No -- next device 

* disk buffer pointer in AO 

* run the code. 

* next device 
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addq 

#4,sp 


move.w 

#$098,(A6) 


move.w 

#$198,(A6) 


move.w 

#$098,(A6) 


move.w 

#1,(A5) 


move.w 

#$088,(A6) 


move.b 

D7,D0 


or.b 

#$08,D0 


swap 

DO 


move.w 

#$088,D0 


bsr 

wcbyte 


bne 

dmr q 


moveq 

#3,D6 


move.l 

#$00008A,D0 

dmr_lp 

bsr 

wcbyte 

bne 

dmr_q 


dbra 

D6,dmr lp 


move.l 

#$00000A,(A5) 


move.w 

#400,D1 


bsr 

wwait 


bne 

dmr q 


move.w 

#$08A,(A6) 


move.w 

(A5),D0 


and.w 

#$00FF,D0 


beq 

dmr r 

dmr_q 

moveq 

#-l,D0 

dmrj 

move.w 

#$080,(A6) 


tst.b 

DO 


sf 

rts 

flock 

Write ASCII command byte and 

wcbyte 

move.l 

D0/A5) 

moveq 

#10,D1 

wwait 

add.l 

Hz_200,Dl 

ww_l 

btst.b 

#5/gpip 


beq 

ww w 


cmp.l 

Hz_200,Dl 


bne 

ww 1 


moveq 

#-l,Dl 

ww w 

rts 



* toggle r/ w, leave at read 

* 

* 

* write sector count reg = 1 

* DMA bus select (not SCR ?) 

* D0.1 to device# + command 

* 

* D0.1=xxxxxxxxDDD01000 

* xxxxxxxxOl 0001 010 

* write cmd and wait for IRQ 

* error exit on timeout 

* write cmd $00 

* cntl $8A 

* four times 

* error exit on timeout 

* 

* write final byte 

* 2s timeout limit 

* 

* error exit on timeout 

* select status register 

* get DMA return code 

* mask for error code only 

* return if o'k 

* set error return (-1) 

* reset DMA chip for drivr 

* test for error return 

* unlock DMA chip 

* 

wait for IRQ 

* write disk controller data 

* wait 0.05s 

* set D1 to timeout 

* disk finished 

* o'k return 

* timeout yet? 

* no — try again 

* set error return (-1) 
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Hard disk partitioning 

Logical sector #0 contains information on the four possible hard disk 
partitions: 

offset 

$1C2 Total size of the disk in sectors 
$1C6 Non zero to show partition exists, 
bit_7 set for BIOS boot partition 
$1C7 Partition start logical sector number 

$1CE Size of partition in logical sectors 
Three further optional partitions 
$1D2 \ $1DE \ $1EA \ 

$1D3 1 2nd $1DF 1 3rd $1EB 1 4th 
$1D6 I $1E2 I $1EE I 

$1DA/ $1E6 / $1F2 / 

$1F6 Staring sector of the bad sector list 

$1FA Number of bad sectors 

$200 reserved 

An ST disk may contain up to four partitions, the first sector of each partition 
is a boot sector and contains a BIOS parameter block. 


The partitions are described by 
the 12 byte structure above. 


Optional partitions 


/ 

The bad sector list is usually held at the end of the device. 
If the parameter ’bsl_cnt’ is zero, there are no bad sectors. 


Root 

boot 

Partition 0 


Partition 1 


Partition 2 


Partition 3 

Optional 
bad sector 
list 


hd_siz 

P°- fl g 

p0_st. 

p0_siz 

P x -flg 

px-id 

px_st 

px_siz 

bsl_st 

bslcnt 
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GENERAL 


The operating system (TOS) is a mixture of GEM and an Atari OS (GEMDOS, 
BIOS and XBIOS as well as the line-A routines). Any of the OS's can completely 
control the system and although calls to the various types of utilities can be 
mixed without restriction, the programmer is advised to use a consistent set of 
calls. There are many reasons for using a consistent set of calls, not the least being 
that the programmer can write programs which are portable to other computers 
that contain the same operating systems. Although the writers present intention 
may not be to provide the program on an alternative computer system, it is wise 
to adhere preferably to the basic OS or GEM calls if possible. Those who have 
programs generated on older 8-bit machines, and now find that they cannot be 
translated easily, will understand the need for portability. 

The line-A routines provide access to the graphic primitives; they will not 
produce portable code but will give very rapid execution of graphic functions. 

Register usage 

The BIOS, XBIOS and GEMDOS routines use and preserve registers in a 
specific manner; dO, dl, d2, aO, al and a2 must always be considered trashed and 
should never be used even though a particular version of TOS does not change 
them, the next version probably will. 

$13 BIOS calls 

$14 XBIOS calls preserve d3 to d7 / a3 to a7 

$1 GEMDOS calls 

Replies are normally held in register DO on return. 

A word of warning. GEM was developed for use on the IBM PC, and as such 
was designed to run the Intel 8088 processor, which stores addresses in memory 
low word first. 68000 GEM uses the same convention in some of the tables and 
parameter blocks, it is a point programmers should be aware of, as a mixture of 
conventions of this kind is likely to cause problems. 

Note that Appendix E provides a list of all the functions and may be used as 
an index to the calls in this and the following chapters. 
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Traps 

BIOS calls (trap #13) 


Trap #13 access 

To access the BIOS functions, push the parameters in the order given onto the 
stack and then call trap#13. Reply or status is returned in register DO and the data 
placed on the stack trashed. 


Typical use might be: 


move.w 

driveA,-(sp) 

move.w 

record,-(sp) 

move.w 

count, -(sp) 

move.l 

addrss,-(sp) 

move.w 

#0, -(sp) 

move.w 

#4, -(sp) 

trap 

#13 

add.w 

#14,sp 

tst.w 

DO 

rts 



* push device code 

* push record to start 

* push number of sectors 

* push buffer address 

* push read data 

* push rwabs function call 

* call the function 

* tidy the stack 

* test for error 


It is the programmers responsibility to tidy the stack after the call. The BIOS, 
accessible from user mode, is re-entrant to three levels of calls, users are advised 
that this non-standard feature should be used wisely where program portability 
is required. 
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BIOS calls (Trap #13) 


Param.Size Description of parameter to push Notes 

pmpb.L: Pointer to MPB structure: Initial values: 

empty memory Memory JreeJist --> MDinBSS 

parameter block Memory jzllocjist — > 0 

to be filled Roving jpointer — > MD in BSS 

[See Appendix F.7] MD structure: 

Next_link_MD — > 0 

(MD=memory descriptor) Start _addr_block -> mbottom 

No.JbytesJblock — > mtop-mbot 

Owner _description — > 0 

getmpb 0 Get/fill a memory parameter block 

(#$00) (Tidy #6) (No return) 

Use this function BEFORE initialising GEMDOS and only with ROM based systems. 

dev.W: device code 0 printer parallel port Operations 

range 1 aux RS232 port 0 and 4 are 

(No range error checking) 2 console screen illegal in 

3 midi this mode. 

4 keyboard Return DO.L 

bconstat 1 Return character_device input status 0 no character 

(#$01) (Tidy #4) (Return DO.L) -1 Char_ready 

dev.W: device code 0 to 3 If dev 2, also WAIT for a 

return IBM-PC compatible code hijvord lojbyte character 
bconin 2 Input character from device DO.L reply. 

(#$02) (Tidy #4) (Return Ascii DO.W) 

If conterm.b ($484) bit 3 set, also returns the keyboard shift status (kbshift_BIOS #11) in 
highest byte (See Appendix A.5 for meaning). 

char.W: character to be sent (Appendix C. 4 for WAIT until 

dev.W: device code 0 to 4 escape codes) character 

bconout 3 Output character to device sent. 

(#$03) (Tidy #6) (Return none) 

dev.w may also use code 5 which outputs to a screen without control characters. 
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BIOS calls (trap #13) cont. 

Param.Size 

: Description of parameter to push 

Notes 

driv.W: 

recn.W: 

secn.W: 

buf.L: 

rwfl.W: 

rwabs 4 

(#$04) 

device code 0 floppy drive A 0 return o'k 

1 floppy drive B negative error 

2+ disks, networks etc. 

logical sector number to start at read/write mode 

number of sectors to transfer 2 & 3 allow 

buffer address (very slow if odd) formatter 

read/write flag 0 read to read & write 

1 write and allow 

2 read \ do not affect BIOS to 

3 write / media-change recognize 

Read/write logical sectors on a device formatted_disk 
(Tidy #14) (Return D0.L) mediachange 

vec.L: 
vecn.W: 
setexc 5 

(#$05) 

vector slot address (-1L no change) 
vector number to set/ get 
Set exception vector (see below) 
(Tidy #8) (Return D0.L) 

0 to FF system 
to $1FF GEM 
to $FFFF OEMs 
(not with GEM) 

tickcal 6 

(#$06) 

Return system elapsed time mS 
(Tidy #2) (Return D0.L) 


driv.W: 
getbpb 7 

(#$07) 

device code (0 to 2+, as per rwabs) 
Get BIOS parameter block pointer 
(Tidy #4) (Return D0.L) 

Boot on $446 
D0.L=address 
0=not found 

dev.W: 
bcostat 8 

(#$08) 

device code_as per bconstat 0 to 4 
Return device char output status 
(Tidy #4) (Return D0.L) 

0=not ready 
-l=ready to send 

driv.W: 
mediach 9 

(#$09) 

device code (0 to 2+, as per rwabs) 

Get media status 

OJMedia no change 
l_Media maybe changed 
2 Media has changed 
(Tidy #4) (Return (D0.L) 

GEMDOS will 
try to read 
media with a 
status value of 1 


BIOS level character output is much faster when implemented through the 
'NEW TOS' ROM's. 
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BIOS calls (trap #13) cont. 

Param.Size 

Description of parameter to push 

Notes 

must be updated by installable disk drives 

Bits 0 - 31 ($4C2) 

drvmap 10 

Get bitmap of drives 

l=drive in 

(#$0A) 

(Tidy #2) (Return D0.L) 

0=drive out 

mode.W: 

Mode bits 7 reserved (zero) 

If mode negative 


6 ALT - Insert 

get IBM-PC 

Note: Not 

5 ALT - Clr/home 

state of 

all GEMs will 

4 CAPS-lock 

shift keys 

read bits 5 & 6 

3 ALT key 

as bit vector 


2 CONTROL key 

in D0.L low 


1 left shift key 

byte. 


0 right shift key 

Critical 

kbshift 11 

Set keyboard shift bits 

code for 

(#$0B) 

(Tidy #4) (Return old shift bits D0.L) 

portability 


Critical interrupt handlers 

The extended GEMDOS vectors (Appendix A.4) may be employed by user 
programs but should take note of the following: 

$100 etv_timer: Word value on stack is number of millisecs since last tick. 

Save all registers 

$101 etv_critic: Stack word value is error number, save registers used. 

To ignore an error set D0.L=0 

To retry an error set D0.L=$10000 

To abort an error set D0.L=sign extend stack parameter. 

$102 etv_term: Abort termination by a longword jump back to the top of the 

calling application or terminate via an RTS 
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XBIOS calls (Trap #14) 

Trap #14 access 


To access 

the extended BIOS functions, push the parameters in the order 

given onto the stack and then call trap#14 from user or supervisor mode. Reply 

or status is returned in register DO. 


Typical use might be: 


moved 

vector ,-(sp) * push vector address 


moved 

parblk,-(sp) * push parameter block addr 

move.w 

type, -(sp) * push type of mouse action 


move.w 

#0, -(sp) * push initmouse call 


trap 

#14 * call the function 


add.w 

#12,sp * tidy the stack 


tst.w 

DO * test for error 


rts 



Param.Size Description of parameter to push 

Notes 

vect.L: 

vector address (mouse interrupt handler) 

If mode = 2 

para.L: 

parameter 1 y=0 top, 0 y=0 bottom 

then extra 

(Block 

block Mouse button command (6.3 #7) 

word sized 

contains 

address x parameter thresh/scale/delta 

parameters 

4 bytes) 

y parameter thresh/scale/delta 

required in 

type.W: 

mode 0 disable mouse 

parameter block 


1 enable relative mouse 

xmax 


2 enable absolute mouse 

ymax 


3 unused 

xinitial 


4 enable keycode mouse 

yinitial 

initmous 0 

Initialize mouse packet handler 

See call #34 

(#$00) 

(Tidy #12) (No return) 

re vector address 

numb.W 

: Bytes from memory top to be saved 

MUST call 

ssbrk 1 

Reserve block of memory at high RAM 

before OS 

(#$01) 

(Tidy #4) (Return D0.L) 

initialized 

physbase 2 

Get screen physical base address 

At next 

(#$02) 

(Tidy #2) (Return D0.L) 

vblank 
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XBIOS calls (Trap #14) cont. 

Param.Size 

Description of parameter to push 

Notes 

logbase 3 

(#$03) 

Get screen logical base address now 
(Tidy #2) (Return D0.L) 

Used by GSX 
on screen 

getRez 4 

(#$04) 

Get screen resolution 
(Tidy #2) (Return D0.W) 

Ret 0 320x200 
1 640x200 
2_640x400 

rez.W: 

ploc.L: 
Iloc.L: 
setScreen 5 
(#$05) 

Set screen resolution (0, 1 or 2) 

clear screen, home cursor, reset VT52 
Set screen physical location (next vblnk) 
Set screen logical location (now) 

Set screen parameters 
(Tidy #12) (No return) 

Negative 
parameters 
are ignored 
so a single 
parameter 
can be set 

palp.L: 
setPalette 6 

(#$06) 

Set palette pointer (word boundary) 
Set palette hardware register contents 
(Tidy #6) (No return) 

At next 
vblank, all 
change. 

colr.W: 
coln.W: 
setColor 7 
(#$07) 

Set colour format -16 bit colour word 
Set colour number (0 to 15) 

Set a colour in hardware palette 
(Tidy #6) Return old colour D0.W 

(with $777 mask) 

If colour 
negative 
ignore. 

secn.W: 
sidn.W: 
trkn.W: 
stsc.W: 
devn.W: 
scrt.L: 
buff.L: 
floprd 8 

(#$08) 

number of sectors to be read 
side number selected (0 or 1) 
track number to seek to 
sector to start reading from (1 to 9) 
floppy device number (0 or 1) 

#0, not used at present, 
word aligned sized buffer address — > 
Read sectors from a floppy drive 
(Tidy #20) 

Return D0.W=0 
for o'k 
else failed 
error number 

must be big 
enough 
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XBIOS calls (Trap #14) cont. 


Param.Size 

1 Description of parameter to push 

Notes 

secn.W: 

number of sectors to write (<=sectors/track) 

Return D0.W=0 

sidn.W: 

side number selected 

for o'k 

trk.nW: 

track number to seek to 

else failed 

stsc.W: 

devn.W: 

sector to start writing to (1 to 9) 
floppy device number (0 or 1) 

error number 

scrt.L: 

#0, not used at present. 

Writing to 

buff.L: 

word aligned buffer address 

boot 1,0,0 

flopwr 9 

Write sectors to a floppy drive 

sets 'maybe' 

(#$09) 

(Tidy #20) (Return D0.W) 

mediachange (1) 


fcod.W: $E5E5 format code (not 0 or FxFx) 

magc.L: $87654321 

intl.W: Sector interleave factor (say 1) 

sidn.W: side number to format (0 or 1) 

trkn.W: track number to format (0 to 79) 

sptk.W: number sectors/track to format (say 9) 

devn.W: floppy device number (0 or 1) 

scrt.L: #0, not used at present. 

buff.L: word aligned buffer address (8K-9track) 

_flopfmt 10 Format a floppy disk 

(#$0A) (Tidy #26) 

The 'NEW TOS' formats a floppy disk with track skew (-1) and a longword pointer to a 
one word per sector skew taole in the previously unused scrt.L parameter 


Return D0.W=0 
for o'k 
else failed 
error number. 
Buffer holds 
Zero terminated 
list of bad 
sectors. 
Formatting 
sets 

mediachange (2) 


getdsb 11 Get device status block pointer Obsolete 

(#$0B) (Tidy #2) (RTS call only) function. 

ptr.L: Pointer to character vector 

cnt.W: number characters to write less one. 

midiws 12 Write a string to midi port 
(#$0C) (Tidy #8) (No return) 


vect.L: Address of interrupt routine Old vector 

intn.W: Interrupt number (0 to 15) is lost. 

_mfpint 13 Set MFP interrupt 
(#$0D) (Tidy #8) (No return) 
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XBIOS calls (Trap #14) cont. 


Param.Size Description of parameter to push Notes 


devn.W: Serial device 0: RS232 

1: Keyboard 
2: Midi 

( L.pntr to device buffer 
( W.size of buffer 
( W.head index 
( W.tail index 
( W. low-water mark 
( W. high-water mark 
iorec 14 Get pointer to serial device i/p brpb 
(#$0E) (Tidy #4) (Return DO.L) 


Return a pointer .L 
to a serial device's 
input buffer record 
parameter block (brpb) 


For RS232 
identical 
o/p buffer 
follows i/p 

High & low 
water start 
RS232 Xon/Xoff 
if flow control 
enabled. 


scr.W: 

Sync character 

\ 68901 


-1 parameters 

tsr.W: 

Tx status 

1 MFP register 

do not 

rsr.W: 

Rx status 

1 settings 


change 

usr.W: 

flow.W: 

Usart control / (page 1.25) 

0 No flow control (default) 

1 Xon/Xoff ( A S/ A Q) 

2 RTS/CTS 

3 Xon/Xoff &RTS/CTS 


registers 

baud.W: 

0=19200 

5=2000 (1920) 

10=200 



1=9600 

6=1800 (1745) 

11=150 

Actual 


2=4800 

7=1200 

12=134 

baud in 


3=3600 (3840) 

8=600 

13=110 

brackets 


4=2400 

9=300 

14=75 (120) 

rsconf 15 

Configure RS232 port 

15=50 (80) 


(#$0F) 

(Tidy #14) 

(No return) 




capl.L: 
shft.L: 
unsh.L: 
keytbl 16 
(#$ 10 ) 


Caps lock \ Set pointers to 128 byte Return pointer 

Shift I Keyboard translation to structure: 

Unshifted / tables. Unshft_tab 

Set/get keyboard translation table pointer Shift Jabl 

(Tidy #14) (Return DO.L) Capslkjab 

-1 not to change characters 


Bit zero poor distribution 

_random 17 Get 24-bit pseudo random number Bits 24-31 

(#$11) (Tidy #2) (Return DO.L) are zero 
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XBIOS calls (Trap #14) cont. 


Param.Size Description of parameter to push Notes 


exfl.W: 

dskt.W: 

sern.L: 

buf.L: 

_protobt 18 

(#$ 12 ) 


1 = boot sector executable 
0 = non-executable boot sector 
0=40 track SS 2=80 track SS 
1=40 track DS 3=80 track DS 
random boot serial no. if= #$1000000 
pointer to any 512-byte buffer 
Prototype a boot sector image 
(Tidy #14) (No return) 


-1 retains 
old values. 

Image is 
written 
to volumes 
boot sector 


secn.W: 

sidn.W: 

trkn.W: 

stsc.W: 

devn.W: 

scrt.L: 

buff.L: 

_flopver 19 

(#$13) 


number sectors to verify (<=sectors/ track) 

side number selected 

track number to seek to 

sector to start reading from (1 to 9) 

floppy device number (0 or 1) 

#0, not used at present, 
word aligned 1024 byte buffer address 
Verify sectors from a floppy drive 
(Tidy #20) 


Return D0.W=0 
for o'k 
else failed 
error number 

Buffer holds 
0 terminated 
list of bad 
sectors.W 


scrdmp 20 Dump screen to printer At present 

(#$14) (Tidy #2) (No return) mono only. 


rate.W: 

attr.W: 


cursconf 21 

(#$15) 


Rate = 1/2 cycle time 

60/50 Hz color 70 Hz monochrome 
0_Hide cursor 4_Set rate 

l_Show cursor 5_Get rate 

2_Blink cursor 6_unused 

3_Noblink cursor 7_unused 

Set/get cursor blink rate & attribs 
(Tidy #6) (Return D0.W) 


-1 retains 
old values. 

Returns 
old rate High 
old attribute low 
word byte. 


date.L: 32-bit DOS format date and time Date Hiword 

settime 22 Set ikbd time and date Time Loword 

(#$16) (Tidy #6) (No return) (See page 3.22 

| f or the format. 

gettime 23 Get ikbd 32-bit format date & time These functions use 

(#$17) (Tidy #2) (Return D0.L) the real time clock 
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XBIOS calls (Trap #14) cont. 

Param.Size 

Description of parameter to push 

Notes 

bioskey 24 
(#$18) 

Restore power up keyboard setting 
(Tidy #2) (No return) 

Reset translation 
tabs 

pntr.L: 
nch.W: 
ikbdws 25 
(#$19) 

Pointer to character string vector 
Count of characters to send -1 
Write a string to intelligent kybd 
(Tidy #8) (No return) 

Send command 
to ikbd 

intn.W: 
jdisint 26 

(#$1A) 

MK68901 interrupt number 
Disable a MK68901 interrupt 
(Tidy #4) (No return) 


intn.W: 
jenabint 27 
(#$1B) 

MK68901 interrupt number 
Enable a MK68901 interrupt 
(Tidy #4) (No return) 


regn.W: 
data.B: 
giaccess 28 
(#$1C) 

PSG register number (00 to OFH) 
Byte to write to register 
Read/write a sound chip register 
Atomic access only (Return DO.B) 

Register ORed 
#$00 read 
#$80 write 

bitn.W: 
offgibit 29 
(#$1D) 

Bit number to be set (Mask AND) 
Atomically set PORT A bit to zero 
(Tidy #4) (No return) 


bitn.W: 
ongibit 30 
(#$1E) 

Bit number to be set (Mask OR) 
Atomically set PORT A bit to one 
(Tidy #4) (No return) 


vec.L: 

data.W: 

cntl.W: 

timr.W: 

Pointer to an interrupt handler 
Byte placed in timer's data register 
Timers control register setting 
Timer number allocations are: 



0_A Reserved for end-users & applications 
1_B Reserved for graphics primarily 
2_C System timer (GEM, DESKTOP etc) 
3_D RS232 baud rate and mere users 
xbtimer 31 Provide control timing facility 
(#$1F) (Tidy #12) (No return) 
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XBIOS calls (Trap #14) cont. 


Param.Size Description of parameter to push Notes 


ptr.L: Pointer to table of bytes (command-data) 

cmd 0 to 15 load register 0 to 15 with data 
cmd 128 load tempreg with databyte 
cmd 129 reg # contents to load into tempreg (rr) 
two's c value to add to tempreg (cc) 
time delay between steps (ad/50) 
terminate on value (ee) 
cmd 130-255 set delay data (ticks) [0=stop] 
dosound 32 Produce a sound 


(#$20) (Tidy #6) 


0 xx 

128 xx 

129 rr cc ee dd 


130 xx 

(See Appendix 
L.22 et seq.) 


conf.W: 

BitO 

0=dot matrix. 

l=daisy wheel 

-1 returns 



1 

0=colour device 

l=monochrome 

configuration 



2 

0=1280.dots/line l=960.dots/line 

byte else 



3 

0=draft, 

1=NLQ 

change and 



4 

0=parallel, 

1=RS232 port 

return the 



5 

0=formfeed, 

l=single sheet 

old value. 



6-14 reserved 





15 

must be zero 



setprt 

33 

Get/set printer configuration byte 


(#$21) 


(Tidy #4) (Return D0.W) 



Structure 

longword 

format 


kbdvbase 

(#$ 22 ) 


MIDI_input (BIOS buffer routine) 
keybrd_err \ Called when - 
MIDI_err / overrun detected 
ikbd_stat \ Pointer to packet 

mous_pack I handlers (pointer to 

packet received in 
AO & on stack. L) 

Call when character 
available on 6850 
Return pointer to structure base 
(Tidy #2) (Return DO.L) 


clock_pack 
joyst_pack / 
MIDIjvec \ 
ikbdjvec / 
34 


— > DO.B character 
\ 68901 

/ or 6850's 

(mouse vector 
used by 
GEM & GSX) 

Handlers to 
return by RTS 
within 1ms 


rept.W: 

init.W: 

kbrate 35 

(#$23) 


Rate of key-repeats (System ticks) 
Delay before key-repeat starts 
Get/set keyboard repeat rate 
(Tidy #6) (Return D0.W) 


-1 parameters 
no change. 
Delay high byte 
repeat low byte 
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XBIOS calls (Trap #14) cont. 

Parana. Size 

1 Description of parameter to push 

Notes 

prt.L: 

prtblk 36 

(#$24) 

Pointer to parameter block 
Hard copy routine 
(Tidy #6) (No return) 


vsync 37 

(#$25) 

Wait till next vblank and return 

(Tidy #2) (No return) 

Graphics 

synchronize 

code.L: 

superx 38 

(#$26) 

Pointer to code ending with RTS 

Hackers access to hardware & protected locations 

Execute code in supervisor mode 

(Tidy #6) 

Must not 
call BIOS 
or GEMDOS 
functions 

puntaes 39 

(#$27) 

Switch off AES, when not in ROM 

(Tidy #2) otherwise perform a RESET. 

flag.W: 

Blitter status word 

bit 0- set to enable blitter 
1-14 reserved 
15 0_clear 

or -l_Get blitter status 

Automatic 
operation 
through line-A 
and VDI calls. 
Return DO 


blitmode 64 Get/set blitter status bit 0_set (blit on) 

(#$40) (Tidy #4) (Return DO. W) l_set (if blit there) 

The reserved fields are for future blitter capabilities 2-14 reserved 

and will be used in future. 15_clear 
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GEMDOS calls (Trap #1) 

Trap #1 access 

To access GEM BDOS functions, push the parameters in the order given onto 
the current stack and then call trap#l . Any byte, word or longword reply or the 
address of a parameter block will be returned in register DO. 

move.W driveB,-(SP) * push drive number (2) 

move.W #13,-(SP) * push setdrv function call 

trap #1 * call the function 

add.W #4, SP * tidy stack 

rts * return with bitmap in DO 

It is the programmers responsibility to maintain the stack integrity (tidy) after 
the call. 


Param.Size Description of parameter to push Notes 

p_term_o 0 End process and return to parent. Return code 

(#$00) (Tidy #2) (use $4c) zero. 


c_conin 1 Read character from standard i/p & echo The console 

(#$01) (Tidy #2) (Return DO.L) scan code 

1 (Appendix 

char.W: Character to be printed page d.3) 

c_conout 2 Write character to standard output is returned 

(#$02) (Tidy #4) (No return) in the low 

1 byte of the 

c_auxin 3 Read character from auxiliary port high word. 

(#$03) (Tidy #2) (Return DO.L) (RS232) The upper 

1 byte of the 

char.W: Character to be printed word sent 

c_auxout 4 Write character to standard aux device MUST be 0 

(#$04) (Tidy #4) (No return) (RS232) for future 

1 compatibility 

char.W: Character to be printed 

c_prnout 5 Write character to standard print device 
(#$05) (Tidy #4) (Return -l_o'k, 0_after 30ms time out) 
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GEMDOS calls (Trap#1) cont. 


Param.Size Description of parameter to push Notes 


parm.W: 


c_rawio 6 

(#$06) 


If parm.W=255 ($00FF) then read else 
parmeter is character to be written 
Raw I/O to standard input/output 
(Tidy #4) (Return DO.L) 


If no character 
then D0.L=0 
Character as 
per c_conin 


c_rawcin 7 Raw input from standard input No echo to screen 

(#$07) (Tidy #2) (Return DO.L) Pass controls 


c_necin 8 Read a character from standard input No echo. A C 

(#$08) (Tidy #2) (No return) A Q & A S active 


addr.L: Address of null terminated string Character bytes 

c_conws 9 Write string to standard output terminated 

(#$09) (Tidy #6) (Return D0.L=# char sent) by a zero. 

addr.L: Address of input buffer On rptnm 

(First byte data portion length) 2nd length read 

c_conrs 10 Read edited string from standard input 3-n characters 

(#$0A) (Tidy #6) (Buffer returns) n+1 zero 

A C A H A I A J A M A R A U,and A X have their normal 'edit' meaning. 
Terminate edit using : RETURN, A J or A M 


c conis 
(#$0B) 

11 

Check status of standard input 
(Tidy #2) (Return DO.L) 

character ready 
-l_yes,0_no 

driv.W: 
d setdrv 14 

(#$0E) 

Drive number: 0=A, 1=B....15=P 

Set default drive 

(Tidy #4) (Return DO.L) 

Return bitmap 
of drives 
present 

c conos 
(#$10) 

16 

Check status of standard output 
(Tidy #2) (Return DO.L) 

-1 ready 
0 not ready 

c prnos 
(#$11) 

17 

Check status of standard print device 
(Tidy #2) (Return DO.L) 

-1 ready 
0 not ready 

c auxis 
(#$12) 

18 

Check status of standard aux device i/p 
(Tidy #2) (Return DO.L) 

-1 char received 
0 no characters 
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GEMDOS calls (Trap#1) cont. 


Param.Size 

; Description of parameter to push 

Notes 

c auxos 19 

Check status of standard aux device o/p 

-1 ready 

(#$13) 

(Tidy #2) 

(Return DO.L) 

0 not ready 

d getdrv 25 

Get current drive 

drive A=0 

(#$19) 

(Tidy #2) 

(Return DO.L) 

B=l...etc. 

addr.L: 

Disk transfer address 

Address 

f setdta 26 

Set disk transfer address 

used by 

(#$1A) 

(Tidy #6) 

(No return) 

sfirst (#78) 

t getdate 42 

Get date 

(as per set date format) 

Date return 

* (#$2A) 

(Tidy #2) 

(Return DO.L) 

in low word 

date.W: 

Date format 

date: bits 0-4, 1 to 31 

Error return 

t setdate 43 

Set date 

mnthbits 5-8, 1 to 12 

if date not 

* (#$2B) 

(Tidy #4) 

year: bits 9-15, 1980 - 2100 

valid 

t gettime 44 

Get time 

(as per set time format) 

Time return 

* (#$2C) 

(Tidy #2) 

(Return DO.L) 

in low word 

time.W: 

Time format 

secs: bits 0-4, step 2s 

Error return 

t settime 45 

Set date 

mins: bits 5-10 

if date not 

* (#$2D) 

(Tidy #4) 

hour: bits 11-15 

(DO.L) valid 

f getdta 47 

Get disk transfer address 


(#$2F) 

(Tidy #2) 

(Return DO.L) 


s version 48 

Get version no. 

(1 .00 lo- hi byte) 

0001 H for 

(#$30) 

(Tidy #2) 

(Return D0.W) 

first release 

exit.W: 

Exit code (process return code) 

May cause 

keep.L: 

# bytes to keep 

in process description 

problems 

p termres 49 

Terminate and stay resident 

for future 

(#$31) 

(Tidy #8) 

(No return) 

conversions 


* Updated from RTC on the termination of every process 
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GEMDOS calls (Trap#1) cont. 

Param.Size 

■ Description of parameter to push 

Notes 

driv.W: 

Drive number: 0=current, 1=A, 2=B.. 

Buffer pb.L 

info.L: 

Address of drive information buffer 

ttfree clusters 

d free 54 

Get drive free space (data in buffer 

ttclusters total 

(#$36) 

4 x longwords) 

ttbytes/sector 


(Tidy #8) (Return D0=0_o'k else error) tt sectors! cluster 

path.L: 

Address of string containing pathname 

Pathname is 

d create 57 

Create a subdirectory 

terminated 

(#$39) 

(Tidy #6) (Return DO.L) 

in a null. 

_ i 

path.L: 

Address of string containing pathname 


d delete 58 

Delete a subdirectory 

0 ret o'k 

(#$3A) 

(Tidy #6) (Return DO.L) 

negative error 

path.L: 

Address of string containing pathname 


d setpath 59 

Set current directory 


(#$3B) 

(Tidy #6) (Return DO.L) 


attr.W: 

File attributes: 01H read only 

Return file 


02H hidden file 

handle if o'k, 


04H hidden system file 

negative error 


08H File, vol label in first 11 bytes 

path.L: 

Address of string containing pathname 


f create 60 

Create a file 

Pathname 

(#$3C) 

(Tidy #8) (Return DO.L) 

ends in a zero 

attr.W: 

File read-write mode 

Return file 


0=file open for read only 

handle if o'k. 


l=file open for write only 

negative if 


2=file open read and write 

error. 

path.L: 

Address of string containing pathname 


f open 61 

Open file 

Pathname 

(#$3D) 

(Tidy #8) (Return DO.L) 

ends in a zero 

hndl.W: 

File handle 

0 ret o'k 

f close 62 

Close file -errors may crash system 

negative error. 

(#$3E) 

(Tidy #4) (Return DO.L) 
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GEMDOS calls (Trap#1) cont. 

Param.Size 

. Description of parameter to push 

Notes 

buff.L: 

Address of buffer to store bytes 

DO contains the 

byts.L: 

Number of bytes to read (never 0) 

number of bytes 

hndl.W: 

File handle 

read. 

f read 63 

Read file 

Negative on 

(#$3F) 

(Tidy #12) (Return D0.L) 

error. 

buff.L: 

Address of buffer storing bytes 

DO contains the 

byts.L: 

Number of bytes to write (never 0) 

number of bytes 

hndl.W: 

File handle (errors may crash the system) 

written. Negative 

f write 64 

Write file 

on error, i.e 

(#$40) 

(Tidy #12) (Return D0.L) 

disk full. 

path.L: 

Address of string containing pathname 

0 return o'k 

f delete 65 

Delete file 

negative on error. 

(#$41) 

(Tidy #6) (Return D0.L) 


fmod.W: 

0: move n bytes from beginning 

Positive moves 


1 : move n bytes from current position 

to end of 


2: move n bytes from end of file 

file, negative 

hndl.W: 

File handle 

to beginning 

nbyt.L: 

Signed number of bytes argument 


f seek 66 

Seek file pointer 

D0=Absolute file 

(#$42) 

(Tidy #10) (Return D0.L) 

pointer location 

attr.W: 

File attributes: #$01 read only 

Return file 

#$02 

hidden file #$04 hidden system file 

handle if o'k, 

#$08 

File, vol label in 1st 11 bytes 

negative if error 

#$10 

File is a subdirectory 


#$20 

File has been written & closed 

Pathname is 

wrt.W: 

0 get/1 set file attributes 

terminated 

path.L: 

Address of string containing pathname 

in a null. 

f attrib 67 

Get/set file attributes 


(#$43) 

(Tidy #10) (Return D0.L) 

Get in D0.L 

shnd.W: 

Standard file handle to duplicate 

Error return 

f dup 69 

Duplicate file handle 

page 1.3 

(#$45) 

(Tidy #4) (Return D0.L) 
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GEMDOS calls (Trap#1) cont. 

Param.Size Description of parameter to push 

Notes 

shnd.W: 
nhnd.w: 
f force 70 

(#$46) 

Standard file handle to force 
Non-standard file handle 
Force point file handle to non-standard 
(Tidy #6) handle file or device 

0 console i/p 
-1 console o/p 
-2 serial 
-3 parallel 

driv.W: 
path.L: 
d getpath 71 
(#$47) 

Drive number: 0=default, l=A...etc. 
Address of 64 byte buffer for pathname 
Get current directory 
(Tidy #8) (Return DO.L) 

Buffer minimum 
64 bytes. 

Return 0_o'k 

nbyt.L: 
m alloc 72 

* (#$48) or 

Allocated block may not be on a word boundary 
Bytes to allocate or -1 return maximum available D0.L=0 if 
Allocate memory (DO.L start pointer) allocation fails 

Read free memory (DO.L bytes available) or pointer to 

(Tidy #6) (Return DO.L) block. 

frad.L: 

m free 73 

* (#$49) 

Address of memory to free 
Free allocated memory 
(Tidy #6) (Return DO.L) 

0 return o'k 
negative on error 

rmem.L: 
mmem.L: 
zero.W: 
m shrink 74 
* (#$4A) 

Length of retained memory 
Start of memory space to modify 
zero (reserved) 

Shrink size of allocated memory 

(Tidy #12) (No return) 

Reallocates 
unused memory 
for GEMDOS. 

0 return o'k 
negative on error 


p_exec 

(#$4B) 


penv.L: Pointer to environmental string, 0 for parent 

pcmd.L: Pointer to command tail including redirection 

path.L: Address of string containing pathname 

mode.W: 0=load & execute, return terminal child code 

3=load only, return DO.L base page address 
4=create basepage, 5=execute only 
75 Load or execute a process 

(Tidy #16) (Return DO.L) 

Insufficient memory error returned as $OOOOOOD9. 


Mode 3 is 
used for 
overlays. 


Return DO.L 
error if 
load fails. 


* These functions are unreliable in early versions of TOS. 
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GEMDOS calls (Trap#1) cont. 


Param.Size Description of parameter to push Notes 


stat.W: 
p_term 76 
(#$4C) 


Interrogation code for parent 
Terminate process, control to parent 
(Tidy #4) (Return DO.L) 


0 Return o'k 
non-zero error 


satt.W: Search attributes Filename 

#$00 normal files: #$01 read only may include 

#$02 hidden files: #$04 hidden system file or '?' 

#$08 volume label file #$10 subdirectory files wildcards. 
#$20 File has been written & closed 
path.L: Address of string containing pathname If file not 

f_sfirst 78 Search for 1st occurence filespec found return 

(#$4E) 44-byte DTA buffer created if found -33 code 

0-20 OS reserved: 21 file attributes in DO.L 

22-23 Time stamp: 24-25 Date stamp (file not found) 

26-29 Filesize.L (Lo-Hi): 30-43 Name.extension 

(Tidy #8) (Return DO.L) 


f_snext 79 Search for next occurence filespec First 20bytes 

(#$4F) (Uses first 20 bytes of DTA buffer, DTA buffer 

name.extension updated on success) must not be 
(Tidy #2) (Return DO.L) altered. 


pth2.L: 

Pointer to 'new' file string 

Rename a 

pthl.L: 

Pointer to 'old' file string 

file 

zero.W: 

zero 

Return DO 

f rename 86 

Rename a file 

error number 

(#$56) 

(Tidy #12) (Return DO.L) 

or 0=o'k 
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GEMDOS calls (Trap#1) cont. 


Param.Size Description of parameter to push Notes 


info.W: 

hndl.W: 

buff.L: 

f_datime 87 

(#$57) 


0_set/l_get date and time 
File handle 

Time and date buffer pointer 
Get/set file date and time stamp 
Buffer first word 
Bit format days 0-4 1 to 31 
mnth5-8 1 to 12 
year 9-15, 1980 to 2100 
Buffer second word 
Bit format secs 0-4 in 2 sec steps 
mins 5-10 
hour 11-15 

(Tidy #10) (No return) 



0 


21 

22 

24 

26 

30 


OS reserved 

File attributes 
File time stamp 
File date stamp 
Longword file size 
Name and ext. of file found 
(7 words) 


DTA buffer 


Use function #$1A (dec 26) to set DTA buffer address and functions #$2F 
(dec 47) to get DTA address. 
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Supervisor/User toggle 

This special function allows users to get in and out of supervisor mod&from 
GEMDOS. 

Param.Size 

' Description of parameter to push 

Notes 

stck.L: 

-l_get mode: Return 0_user 

(DO.L) l_supervisor 



o-l switch mode 

Return 


a) User to supervisor mode 

value of 


0_set supervisor stack equal 

old super 


to user stack before call 

stack in 


<>0_set supervisor stack equal 
to stck.L 

DO.L 


b) Supervisor to user mode 

The old 


set supervisor stack from 

value of 


stck.L which must be the first 

super stack 


SMODE function call or the 

MUST be 


system will crash. 

restored on 

sinode 32 

Set/get supervisor/user mode 

process 

(#$20) 

(Tidy #6) (Return DO.L) 

termination 


Test for mode 


move.L #$l,-(sp) 

move.W #32,-(sp) 

trap #1 

addq #6,sp 


* Returns DO.L 

$0= user mode 
$FF=supervisor mode 


User to supervisor mode 

clr.L -(sp) 

move.W #32,-(sp) 

trap #1 

addq #6,sp 

move.L D0,save_stk 

Supervisor to user mode 

move.L save__stk,-(sp) 
move.w #32,-(sp) 

trap #1 

addq #6,sp 


* Set supervisor stack equal to 

* user stack before this call, 

* 

* 

* Save old supervisor stack value 

* Recover old supervisor stack 

* 

* and back into user mode. 

* 
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Extended BDOS calls (Trap #2) 


To access the extended BDOS functions, the DO.W register is loaded with the 
function code, an address pointer is placed in Dl.L and trap #2 called. A return, if 
any, is placed in DO.W. 

GEM VDI and AES may be accessed by loading the relevant parameter block 
address into Dl, the function number into dO and making an extended BDOS call: 

GEM VDI access 

moved #contrl, pblock 
moved #pblock,dl 

move.w #$73,d0 
trap #2 


GEM AES access 

moved #control,_c 

moved #_c,dl * address of AES param block 

move.w #$c8,d0 * set dO equal to 200 and 

trap #2 * execute an extended BDOS call 


* address of VDI param block 

* set dO equal to 115 and 

* execute an extended BDOS call 
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Extended BDOS calls (Trap #2) cont. 


Code# 

Hex Dec 

Function Notes 


DO.W : 
Trap #2 

#$oo o 

Terminate current program and 
return to CP level 
RESET 

The function 
does not return 
to calling program 

Dl.L : 
DO.W: 
Trap #2: 

#pblock 
#$73 115 

VDI parameter block pointer 
VDI function number 
GEM VDI access 


Dl.L: 
DO.W : 
Trap #2: 

#control 
#$c8 200 

AES param block pointer 
AES function number 
GEM AES access 


DO.W: 
Trap #2 

#$c9 201 



DO.W: 
Trap #2 

#$fe -2 

Test for GDOS version 

Return D0.W=-2 
if GDOS not 
installed. 


The trap #2 RESET call simply calls the GEMDOS trap #1 process terminate 
function #$4C. 


* Test for GDOS, looks for Atari GDOS version 1.0 which does not contain all 
the VDI functions. 
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Interrupt Handler 

The standard system interrupt is level 2, vector $68 (104) and takes the 
following sequence every interrupt: 

Vertical blank interrupt (VBI) 


Order 

Function 

System variable 


1 

Increment the frame counter 

FRCLOCK.L 

$466 

2 

3 

Test for mutual exclusion 
if = 0 return 

Save all the registers on stack 
Increment 'Vblank counter' 

VBSLEM.W 

$452 

4 

VBCLOCK.L 

$462 

5 

Test for high resolution mode 
if shftmd<2 then goto 6, 

SHFTMD.W 

$44C 


test for low resolution monitor attatched 

if yes set mode to zero DEFSHFTMD.B $44A 

6 Call cursor blink routine 

7 Test for new colour pallette COLORPTR.L $45A 

if colorptr=0 then goto 8 

Load pallette with 16 words pointed to 

by colorptr and then zero it. 

8 Test for new screen SCREENPTR.L $45E 

if screenptr=0 then goto 9 

Set screen physical base to screen 

pointer and then zero pointer. 

9 Run deferred VBI vectors 

# of deferred VBI vectors nvbls.W $454 

Pointer to VBI vector array vblqueue.L $456 

10 Return 

There are eight VBI vectors available in the default array, the first is reserved 
for GEM's VBI code. Pointers to new handlers are placed in the spare slots. 
Handler code ends in RTS and may use any register except the user stack pointer. 
Larger arrays can be allocated by redefining nvbls and vblqueue, copying the 
current vectors to the new array. An application that returns, should tidy up the 
VBI queue. 

Do not make VDI or Line-A calls via an Interrupt as the results are 
unpredictable if the ST has a blitter chip installed. 
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GEM VDI 
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GEM VDI function calls 


Digital Research's GEM VDI (Virtual Device Interface) provides graphic 
capabilities and a device independent operating environment for the 
development of programs that are transportable to other operating systems. It is 
therefore a pity that the initial ROM implementations of the Atari ST did not 
include that portion of code which provided the transportability. 

The VDI comprises GDOS, the Graphics Device Operating System and GIOS, 
the Graphics Input/Output System. 

GDOS consists of the basic and device independent graphic functions that are 
called by applications and functions without reference to any specific hardware 
in a manner similar to the disk operating system. The GIOS consists of the device 
specific code that is needed to interface to each specific graphic device (device 
drivers). The OS needs a device driver for every different graphics device 
attatched to the system, unfortunately only one is supplied - for the screen. This 
limitation, the drivers restriction of only two fonts per screen resolution and the 
absence of support for the normalised device coordinate system means that the 
ST does not have a device independent capability. 

Appendix E lists all the GEM VDI functions. As a general rule, only those 
functions associated with the screen are implemented (virtually all are), those 
associated with either a printer, plotter or meta-file are not implemented. 

It may be possible to obtain the file GDOS.PRG which when placed in an 
AUTO folder, provides the ST with the missing facilities of GDOS. Atari have 
made the file available to registered software developers for a nominal sum but 
the code (and that means small parts of it as well) is subject to a single fixed 
licence fee if used in commercial programs. 
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GEM VDI function calls 


The VDI functions are accessed through an extended BDOS call and the VDI 
parameter block (five longword pointers to the word tables; cntrl, input attribute 
and points, output attribute and points). The parameter and array blocks, which are 
usually initialized by an AES call to APPLINIT, have the following formats: 


$00 

Control 
pointer table 

$04 

Input attribute 
table pointer 

$08 

Input points 
table pointer 

o 

O 

Output attribute 
table pointer 

$10 

Output points 
table pointer 



$00 

Opcode 

$02 

Length of input 
coordinate table 

$04 

Length of output 
coordinate table 

$06 

Length of input 
attribute table 

$08 

Length of output 
attribute table 

$0A 

Subfunction 
ident number 

$0C 

Device handle 

$0E 

Opcode depend 
information 


control 

intin 

ptsin 

intout 

ptsout 


VDI parameter 
block 


Control table 


Length in 
word pairs 


Length in 
words 


Zero if can not be opened 


It is the programmers responsibility to define the correct number of arguments 
to be passedand the array size (1 to n) required by the function on return. 
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Attribute table 


intin 

intout 



Typical usage 


device ID (handle) 
line type 
line colour 
mark type 
mark colour 
font 


Note: These parameters 

are held in word sized tables. 
Assembler and BASIC use the 
actual offset whereas 'C', Pascal 


Points table 


and GFA Basic etc. use word 


ptsin 



Typical usage 


x coordinate \ word 

y coordinate / pair 


width \ word 

height / pair 


sized offsets, i.e half the actual 
value I have used in this book. 


A minimum application stack space of 128 bytes is required, plus space for 
the GEM arrays. The VDI function calls have been detailed in groups as follows: 

Workstation control functions: 

Define the workstation parameters and defaults; these govern the font and 
the window size to be used and the generation of virtual screens. 

Output functions: 

These functions draw the graphic primitive on the specified output device. 

General drawing primitive functions: 

Contain the basic graphic primitives of line, arc, filled and unfilled ellipse 
and rectangle, and of justified text. 

Attribute functions: 

Define the output style of the graphic primitives; the line, marker, text cell 
and polygon for colour, size and fill. 
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Raster operations: 

Provide the ability to transpose a source block of pixels to a destination 
location on the basis of a logical operation between the bits comprising the source 
and destination. 

Input functions: 

Enable the programmer to provide the user with both a 'request and wait on 
event' and a 'request, sample and return' mode of inquiry. 

Inquire functions: 

Return the status or attributes of a specific device 

Escape functions: 

Enable the application to access special features applicable to certain graphic 
devices. 


VDI Parameter block sizes 

The numbers of parameters required by the various functions are detailed in 
the tabular format: 

Control table 


Pointpair Integers Device 

Function Op in out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 


The table contains details of the parameter input and output word sizes; note 
that the points value is half the table size (a point is defined by a pair of x and y 
word-sized coordinates - a longword). All data is assumed to be 2 byte integer 
including string characters. 

Open workstation function v_opnwk 

The major VDI function in terms of size is the 'open workstation function', 
which sets up a named screen, (device handle) the desktop window, identified as 
device name zero. The new screen is initialized to graphics mode, cleared and the 
parameter table outputs initialized. The v_opnwk (op_l) function is not available 
on the Atari ST (only with GDOS.PRG), programmers should use the virtual 
workstation function vjjpnvwk (op_100). 
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The control table 


Control 

Data 

Array 


offset 


entered 

size.B 

Function 


$0 

0 

1 


Opcode for 'open workstation' 


$2 

2 

0 

0 

# of i/p point pairs 

ptsin 

$4 

4 

6 

24 

# of o/p point pairs 

ptsout 

$6 

6 

11 

22 

Length of i/p attribute table 

intin 

$8 

8 

45 

90 

Length of o/p attribute table 

intout 

$A 

10 



Not used 


$C 

12 

X 


Handle for this device 

(out) 


Attribute input table (intin) 


In tin 
Offset 

Initial defaults (style, colour etc.) 

VDIOp 

code 

$0 

0 

Device driver (screen = 1) 


$2 

2 

Linetype (solid = 1) 

15 

$4 

4 

Polyline colour index 

- 

$6 

6 

Marker type (dot = 1) 

18 

$8 

8 

Polymarker colour index 

20 

$A 

10 

Text face 

21 

$C 

12 

Text colour index 


$E 

14 

Fill interior style 

23 

$10 

16 

Fill style index 

24 

$12 

18 

Fill colour index 


$14 

20 

NDC to RDC transform flag (2 only) 



0 map full NDC to full RC 

1 reserved 

2 Raster coordinates 


The input ranges required to open a workstation with a specific attribute can 
be found, in the table box for that attribute, later in this chapter. 

The procedure names are limited to the maximum of eight unique characters 
supported by the most C compilers. Note that C external names are prefixed by a 
'_' which reduces the uniqueness to seven characters. 
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Attribute output table (intout) 


Intout Default output parameters Typical b&w 

Offset values 


$0 0 Maximum pixel width 

$2 2 Maximum pixel height 

$4 4 Device coordinate flag (0=fine, l=coarse) 

$6 6 Pixel height, microns mm/ 1000 

$8 8 Pixel width, microns mm/ 1000 

$A 10 # character heights (0=continuous) 

$C 12 # linetypes 

$E 14 # line widths (0=continuous) 

$10 16 # marker types 

$12 18 # marker sizes (0=continuous) 

$14 20 # faces supported (fonts) 

$16 22 # patterns 

$18 24 # hatch styles 

$1A 26 # simultaneous colours (2=mono) 

$1C 28 # generalized drawing primitives 

List of the first 10 GDP's (-1 ends list) 
$lE-$30 l=Bar 6=Elliptical arc 

2=Arc 7=Elliptical pie 
30-48 3=Pie slice 8=Rounded rectangle 

4=Circle 9=Filled rounded rectangle 
5=Ellipse 10=Justified graphic text 
Attribute list for GDP's 
$32-$44 0=Polyline l=Polymarker 

50-68 2=Text 3=Fill araea 4=None 


$27f 639 

$18f 399 

always 0 

372 

372 

3 

7 
0 
6 

8 
1 

$18 24 

$c 12 

2 

$a 10 


1 to 10 

303 

330 

303 

2 


$46 

70 

Colour 

\ 0=no, l=yes 

0 

$48 

72 

Text rotation 

1 Capability 

1 

$4A 

74 

Fill area 

1 flags 

1 

$4C 

76 

Cell array operation 

/ 

0 

$4E 

78 

# colours (2=mono, 4, 16) 

2 

$50 

80 

# locator devices 

l=keyboard only 
2=keyboard + i/p (mouse) 

2 

$52 

82 

# valuator devices 

l=keyboard 

1 

$54 

84 

# choice devices 

l=function keys 
2=button device 

1 

$56 

86 

# string devices 

l=keyboard 

1 

$58 

88 

# Workstation type 
1— i/p only, 
3=reserved, 

0=output only 
2=input/output 
4=metafile output 

2 
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Output points table (ptsout) 


Ptsout 

Offset 

Output points table 


Typical 

values 

$0 

0 

Minimum character width 


5 


$2 

2 

Minimum character height 


4 


$4 

4 

Maximum character width 


7 


$6 

6 

Maximum character height 

$d 


13 

$8 

8 

Minimum line width 


1 ’ 


$A 

10 

Zero 


0 


$C 

12 

Maximum line width 

$28 


40 

$E 

14 

Zero 


0 


$10 

16 

Minimum marker width 

$f 


15 

$12 

18 

Minimum marker height 

$b 


11 

$14 

20 

Maximum marker width 

$78 


120 

$16 

22 

Maximum marker height 

$58 


88 


The GEM VDI calls 

Workstation control functions 


The following functions set the workstation parameters and defaults for use 
by the application: 


Pointpair Integers Device 

Function Op in out in out GDP name 

$0 $2 $4 $6 $8 $A $C 

Open 1 0 6 11 45 zero 

workstation 

* v_opmvk Call only with GDOS.PRG installed 


Comments 


Set up desktop window 
(device zero) to graphics 
mode & initialise tables 


* Not implemented on the Atari ST 
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Workstation control functions cont. 


Function Op 
$0 


Close 2 
workstation 
* v_clswk 


Open 100 
virtual 
screen 
v_opnvwk 


Close 101 
virtual screen 
v_clsvwk 


Clear 3 
workstation 
v clrwk 


Pointpair Integers Device 

in out in out GDP name 
$2 $4 $6 $8 $A $C 


0 0 0 0 

Call only with GDOS.PRG installed 


0 6 11 45 i/p screen 

parameters 

as opcode 1 o/p new 

(pg 4.6 Intin) window 


0 0 0 0 


0 0 0 0 


Comments 


Return to alpha mode 
Close device and 
flush buffers. 


Permits multiple 
windows based on 
one screen with 
different attributes 


Close virtual screens 
first to stop further 
output to screen. 


Clear the screen. 

New page if possible. 
Delete buffer data 


Update 4 0 0 0 0 

workstation 

v_updwk 


Load 119 0 0 1 1 

font intin (0)=0, reserved 

intout(0)=# fonts loaded 

* vstjoadjonts 


Unload 120 0 0 1 0 

font intin (0)=0, reserved 

* vst_unloadJonts 


129 2 0 1 0 

a b — intin(0)=0_off (default) 

i I <>0 on 


angle 

clip 


Execute graphic 
commands waiting. 
No effect on screen. 
Use to print data 


Load additional 
fonts. 

intin(0) reserved 
for future use. 


Unload font from 
memory if no other 
live users. 
intin(0) reserved 


Disable /enable 
clipping of 
output primitive, 
ptsin a,b,c,d 
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Output Functions 

The following functions draw the graphic primitives (lines, arc etc.) on the 
current device using the current attributes. 


Function 

Op 

$0 

Pointpair Integers Device 

in out in out GDP name 
$2 $4 $6 $8 $A $C 

Comments 

Polyline 

6 

3 

o 

o 

0 

Draw line between 

v_pline 

min of 2 coord pairs 

xl,yl x2,y2 etc . 

n pairs of points 

Poly- 

7 

n 0 0 

0 

Draw marker at 

marker 




each of n pairs 

vjpmarker 


xl,yl x2,y2 

! etc. 

of points. 

Text 

8 

1 0 n 

0 

Write character string 



intin (0)=text string (n=string length) 

to device. 0-255 



ptsin (0)=lower left corner 

Intin word LSByte 

v_gtext 


ptsin (2)=upper right corner 

contains character. 

Filled 

9 

n 0 0 

0 

Outline if device 

area 


n* x,y points as \ 

)er polyline 

can not fill. Close 

vjillarea 


Uses Op #25 vsf_ 

color for fill colour 

area if open. 

Fill 

114 

2 0 0 

0 

Rectangular area fill 

rectangle 


a b ■ i 

ptsin (0)=a ptsin (4)= 

=c ptsin a,b,c,d 




ptsin (2)=b ptsin (6)= 

=d 

vr_recfl 


1 c,d 

Uses Op #25 vsf_color for fill colour 



Cell 
array 

Rect 
array 

Row length Xc Cntrl $E 

#Words/row Cntrl $10 

# Rows Xc Cntrl $12 

Writing mode Cntrl $14 

v_cellarray 


n 0 

n=length of colour index 


Colour 

index 

array 


Xc 


□ 

(Intin 0 . . .n) 


Not implemented in all systems 


Draw rectangular 
cell array, 
ptsin a,b,c,d 
based on colour 
cells Xc * Yc 


Writing mode see 
Op #32 


Contour 103 1 0 1 0 

fill in tin (0)=colour index 

ptsin (0)=x coordinate TStarting 
v_contour ptsin (2)=y coordinate Jpoint 


Flood fill area bound 
by edge or colour. 
There must not be 
a gap 
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General drawing primitive functions (GDP’s) 

The GDP's provide the basic graphic primitives of line, arc, ellipse etc. 




Pointpair Integers 

Device 

Function 

Op 

in out in out GDP name Comments 


$0 

$2 $4 $6 $8 $A 

$C 

GDP 

11 

n - - - x 

_ 

(General format) 


Bar 

11 

2 0 0 0 1 

Area attributes 


ptsin (0)=corner x coordinate 



ptsin (2)=corner y coordinate 

Uses Op #25 


ptsin (4)=diagonally opposite x coordinate vsf color attributes 

v_bar 

ptsin (6)=diagonally opposite y coordinate 

Arc 

11 

4 0 2 0 2 

Line attributes 


ptsin (0)=centre x coordinate 

ptsin (C)=radius 


ptsin (2)=centre y coordinate 

ptsin (E)=0 


ptsin (4)=0 ptsin (8)=0 

intin (0)=start angle"] 0 to 

v_arc 

ptsin (6)=0 ptsin (A)=0 

intin (2)=end angle J 3600 



New TOS' clears reliability problems of small angles. 


11 

4 0 2 0 3 

Area attributes 

vjpieslice 


Parameters as per arc above 


Circle 

11 

3 0 0 0 4 

Area attributes 



ptsin (0)=centre x coordinate ptsin (6)=0 



ptsin (2)=centre y coordinate ptsin (8)=radius 

vjcircle 


ptsin (4)=0 

ptsin (A)=0 

Ellipse 

11 

2 0 0 0 5 

Area attributes 



ptsin (0)=centre x coordinate 



ptsin (2)=centre y coordinate 



ptsin (4)=radius x axis 


v_ellipse 


ptsin (6)=radius y axis 


Elliptic 

11 

2 0 2 0 6 

Line attributes 

arc 


ptsin (0)=centre x coor 

intin (0)=start angle-] 0 to 



ptsin (2)=centre y coor 

intin (2)=end angle J 3600 



ptsin (4)=radius x axis 


v_ellarc 


ptsin (6)=radius y axis 
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GDP’s cont. 


Pointpair Integers Device 

Function Op in out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 


GDP 11 n - - - x - 

(General format) 

Elliptic pie 11 2 0 2 0 7 - Area attributes 

v_ellpie Parameters as per elliptic arc above 

Rounded 11 2 6 0 6 8 - Line attributes 

rectangle ptsin ( 0 )=corner x coordinate 

ptsin ( 2 )=corner y coordinate 
ptsin (4)=diagonally opposite x coordinate 
vjbox ptsin ( 6 )=diagonally opposite y coordinate 

Filled li 26069 - Area attributes 

rounded 

rectangle 

vjrfbox Parameters as per rounded rectangle 


Justified 11 2 0 2+n 0 10 - Text attributes 

graphics in tin ( 0 )=interword space flag *1 zero to 

text intin ( 2 )=intercharacter space flag] keep as is 

intin (4)=first character -| Null terminated 
intin (4+n)=last characterj string 
ptsin ( 0 )= x alignment 
ptsin ( 2 )= y alignment 
ptsin (4)= string length 
ptsin ( 6 )= zero 

v Justified Intin uses least significant byte of word for character 


Notation used for 
angular specification 



0 
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Attribute functions 

The attribute functions determine the output style of all the graphic 
primitives; that is colour, line style, character size etc. 


Function 

P p 

$0 

Pointpair Integers Device 

in out in out GDP name 
$2 $4 $6 $8 $A $C 

Comments 

Set 

32 

0 0 1 1* 

Out of range uses 

writing 


intin(0)=l,replace 

replace mode 

mode 


=2,transparent (mask l's) 

Modes 2, 3 and 4 



=3,XOR 

based on line or 

vswrjnode 


=4,reverse transparent (mask 0's) 

fill pattern mask 


Set a 
colour 


vs color 


14 0 0 4 0 - Redefine a colour. 

v_opnvwk (intout $1A) gives # colours No action if lookup 
intin (0)=colour index In mono table is not available 
intin (2)=red \ Colour any colour or 'out of range' 

in tin (4)=green I intensity is set to The number of colours 

intin (6)=blue / 0 to 1000 white is device dependent. 

15 0 6 T l* “ 

v_opnvwk (intout $C) gives # linetypes 
intin (0)=line style 

l=solid 2=long dash 3=dot 4=dash-dot 
5=dash 6=dash-dot-dot 7=user defined. 


Set 

polyline 
line type 

vsljtype 


Most devices support 
at least six line styles 


Set user 
defined 
polyline 
vsl_udsty 

Set 

polyline 
width 
vsl width 


113 0 0 1 0 

Sets linetype #7 

intin (0)=line pattern (16 bits) 


User defined pattern 
for line, 

MSB is first pixel. 


16 1 


0 


0 


ptsin (0)=line width 
ptsin (2)=zero 

”o 


On error width is set 
to the nearest below 
ptsout(0)=width Use odd numbers 
ptsout(2)=zero >= three. 

Set colour for polyline 
operations 


Set polylinel7 

colour 

vsl color 


0 


1 


V 


intin (0)=colour index 
.......... --- 


Set 

polyline 
end style 
vsl ends 


108 


intin (0)=start intin (2)=end 


0=square (default) 

l=arrow 

2=rounded 


* denotes intoutO is actual value of intinQ used. 
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Attribute functions cont. 


Function Op 
$0 

Pointpair Integers 
in out in out GDP 

$2 $4 $6 $8 $A 

Device 

name Comments 

$C 

Set 18 

0 0 1 

1* 

All devices support 

polymarker 



at least six markers 

type 

in tin (0)=marker type 

Defaults on error 


l=dot 

2=plus 

3=asterisk to asterisk. 

vsmjype 

4=square 

5=cross 

6=diamond 

Set 19 

1 1 0 

0 

Height set is nearest 

polymarker 



below on error. 

height 

ptsin (0)=zero 


ptsout(0)=x-axis width 

vsm_height 

ptsin (2)=y-axis 

; height 

ptsout(2)=y-axis height 

Set poly- 20 

0 0 1 

1* 

Set colour for 

marker colour 



polymarker 

vsm_color 

in tin (0)=colour index 

operations. 


Set 12 1 2 0 0 

character height ptsin (0)=zero ptsout(O) 
ptsin (2)=height ptsout(2) 
ptsout(4) 

vst_height ptsout(6) 

Set 107""6” 2 T F 

character cell intin (0)=cell ht ptsout(O)- 

height in point size ptsout(2) : 

(1 point=[72 inch) 

vstjpoint 


Size of character 

^character width 
^character height 
=cell width 
=cell height All i/p's in raster units 


V. 


character 


ptsout(4)= 

ptsout(6): 


"STze'of cell" 


character width 
character height 

cell width 

;cell height Ptsout in raster units 


V 


cell 


Set char 
baseline 
vector 
vst_rotation 

13 

0 0 11* 

v_opnmvk (intout $48) gives capability 

intin (0)=angle requested 

Angular range 
0 to 3600 

Not supported by 
all devices. 

Set text 

face 

vstjont 

21 

0 0 11* 
intin (0)=face selection 

Face 1 is built-in 
(System face) 

Set graph 
text colour 
vst_color 

22 

0 0 11* 
intin (0)=text colour index 

Set colour for 
next text, 
default 1 


* denotes intoutO is actual value of intin() used. 
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Attribute functions cont. 


Function Op 
$0 

Pointpair Integers Device 

in out in out GDP name 
$2 $4 $6 $8 $A $C 

Comments 

Set text 106 
special 
effect 
vst_effects 

0 0 11* - Default to standard 

text 

intin (0):bits 0 to 5 set effects Effect 'on' if bit = 1 

Thick, light, skew, underline, outline, shadow respectively 

Set 39 

graphic text 
position 
vst_alignment 

0 0 2 2* 
in tin (0)=0,left l,centre 2,right 
in tin (2)=3,4,0,1,2,5 respectively 
bottom, descent, base, half, ascent, top 

Left / right / centre 
justify. Vertical position 
defaults to base (zero) 
See pg 4.26 

Set fill 23 

interior style 
vsfjnterior 

0 0 11* 

intin (0)=0 to 4 respectively 

Hollow, solid, pattern, hatch, user-defined 

Set future polygon 
fill style 


0 0 11* 

intin (0)=0 solid colour \ 

2.1 to 24 patterns See pg 4.26 

3.1 to 12 hatch / 

Set pattern or hatch 
type. No effect if 
interior hollow, solid 
or user defined. 

Set fill 25 

colour index 
vsf_color 

0 0 11* 
intin (0)=colour index 

Set future polygon 
fill colour 

Set fill 104 

peri visible 
vsfjperimeter 

0 0 11* 

intin (0)=0_invisible, <>0_visible 

Set on/off 
fill outline 

Set user 112 
-defined 
fill pattern 
vsf_udpat 

0 0 16*n 0 

intin (0-15)=lst plane 
intin (16-31)=2nd plane etc. 

Pattern 16 words /plane 
Bit 15 of word_l upper 
left bit. Bit 0 last_word 
lower right bit 


Notation used for 
angular specification 



*0 


* denotes intoutQ is actual value of intin() used. 
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Raster operations 


Raster operations are the manipuation of rectangular blocks of bits in 
memory or pixels on screen, the area is defined in memory form definition blocks 
(MFDB) that consists of: 


$00 

$04 

$06 

$08 

$0A 

$oc| 

$0E 


Memory pointer 
Width in pixels 
Height in pixels 
Word width 
Format flag 
Memory planes 
Reserved 


32-bit address of pixel 0,0 
Raster area dimensions 

Pixel width/word size 
1 =standard, 0=device specific 
#planes in raster area 
3 reserved words 


The raster planes word-bit-pixel relationship follows the format shown in the 
TOS overview 2.13, the top left hand corner pixel address being 0,0 

Colour index table 


Pixel Index Colour Pixel Index Colour 


0000 

0 

white 

1000 

9 

grey 

0001 

2 

red 

1001 

10 

light red 

0010 

3 

green 

1010 

11 

light green 

0011 

6 

yellow 

1011 

14 

light yellow 

0100 

4 

blue 

1100 

12 

light blue 

0101 

7 

magenta 

1101 

15 

light magenta 

0110 

5 

cyan 

1110 

13 

light cyan 

0111 

8 

low white 

1111 

1 

black 


Raster operations perform logical translations of the source to the destination 
over the original destination pixel area. The required logic operation is passed as 
an argument in intin(0) as follows: 


Mode Function Mode Function 


0 

D'=0 (all white) 

8 

D'=NOT [S OR D] 

1 

D'=S AND D 

9 

D'=NOT [S XOR D] 

2 

D'=S AND [NOT D] 

10 

D'=D INVERT 

3 

D'=S 

11 

D'=NOT D 

4 

D'=[NOT S] AND D 

12 

D'=S OR [NOT D] 

5 

D'=D 

13 

D'=[NOT S] OR D 

6 

D'=S XOR D 

14 

D'=NOT [S AND D] 

7 

D'=S OR D 

15 

D'=l (all black) 


S=Source 


Mode 3=replace 


D= Destination 


Mode 4=erase 


D'=Destination pixel final state 


Mode 6=XOR 
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Raster operations 


Pointpair Integers Device 

Function Op in out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 


Copy 109 4 0 1 0 

raster ptsin ()=a / b / c / d,e,f,g,h order 

opaque intin (0)=logic operation 

cntrl $E=Address.L of source MFDB 

cntrl $12=Address.L of destination MFDB 
vro_cpyfm 


Copy rectangular 
block from source to 
destination. 

If source <> dest 
then source size used 


r~ 

— c,d 

1 Source 

a,b — 

1 

■ 

— g,h 

r 

I Destination 

e,f — 

■■■■■.. J 


Copy 121 4 0 3 0 

raster ptsin ()=a,b,c,d,e / f / g,h order 

transparent intin (0)=write mode 

intin (2)=colour for l's 
intin (4)=colour for 0's 
cntrl $E=Address.L of source MFDB 
cntrl $12=Address.L of destination MFDB 
write_mode a replace 

b transparent (mask l's) 
c XOR mode 

vrt_cpyfm d reverse transparent (mask 0's) 


Copy mono block 
from source to 
destination 
If source <> dest 
then source size used 


| Source 
a,b I 


9,h 


,f 


Destination 


Transform 110 0 0 0 0 - Toggle raster area 

form from standard to 

cntrl $E= Address. L of source MFDB device-specific form, 

cntrl $12=Address.L of destination MFDB 
vrjrnfm The destination block must be verified 


Get 105 1 0 0 2 - Return pixel value 

pixel and colour index 

ptsin (0)=x coordinate intout(0)=pixel value (0 or 1) 
v_get_pixel ptsin (2)=y coordinate intout(2)=colour index 
Background colour is accessible on only some devices. 
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Input functions 

There are two types of input function generally provided by GEM: 

'Request and wait' for reply 
and 'Request and sample' current status. 


Pointpair Integers Device 

Function Op in out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 


Set 111 0 0 37 0 

mouse intin (0)=x coordinate 

form intin (2)=y coordinate 

intin (4)=1, reserved 
intin (6)=mask colour 
intin (8)=data colour (usually 1) 
intin ($A-$28)=16 word mask bits pixel. 
vscjorm intin ($2A-$48)=16 word data bits 

Exchange 118 6 6 0 1 

timer interrupt cntrl $E=Address.L of new routine 
vector return cntrl $12=Address.L of old routine 

vexjimv intout(0)=milliseconds per tick 

Show 122 6" 6 T 0~ - 

cursor intin (0)=0, show cursor 

<> 0, show if # of 

v_show_c show calls = # hide calls 

Hide cursor 123 0 6 0 6 

v_hide_c Operates as per 'show cursor' 


Redefine cursor pattern 
Bit 15 of word_l upper 
left bit of pattern. 


Data under mask is 
saved. 

Goto user- written 
interrupt routine 
on timer tick. 
Disable interrupts 

Show cursor if 
'show'='hide' or 
intin(0)=zero 


Hide cursor (default) 


Sample 124 0 1 0 1 - Return button state 

mouse ptsout(0)=x coor \ cursor 0=none l=left key 

button state ptsout(2)=y coor / 2=right key 3=both keys 

vqjnouse intout(0)=return button state 


Exchange 125 
button 

change return 
vector 
vex butv 


0 0 0 0 

cntrl $E=Address.L user routine 

cntrl $12=Address.L old routine 

(Save and restore registers) 


Go to routine on 
button state change 
Uses D0.W for button 
keys as above. 

Disable interrupts 


4.18 












GEM VDI 


Input functions cont. 


Pointpair Integers Device 

Function Op in ' out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 


Exchange 126 0 0 0 0 

mouse cntrl $E=Addr.L user routine 

movement return $12=Addr.L old routine 
vector x any coords may be changed 

vexjnotv after being stored in hardware register 


Goto routine on 
mouse movement. 
Uses D0.W&D1.W 
to store x & y. 
Disable interrupts 


Exchange 
cursor 
change 
vector 
vex curv 


127 0 0 0 0 

cntrl $E=Addr.L user routine 
return $12=Addr.L old routine 
routine can be used to draw 
special cursor. 


Goto routine on 
cursor state change 
Uses D0.W&D1.W 
to store x & y. 
Disable interrupts 


Sample 128 0 0 0 

1 

Return current state 

keyboard intout(O), bit 

0, right shift 

of Keyboard shift-alt 

state 

1, left shift 

- control keys. 

information 

2, Control 

Zero bit key up 

vq_key_s 

3, Alternate 

One bit key down. 


Functions calling user written code should not enable interrupts 
Registers may need to be restored. 
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The following GEM VDI functions are not implemented in the Atari ST ROM, 
but are included for completeness: 


Input functions (Not implemented) 


Pointpair Integers Device 

Function Op in out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 

Set 33 6 6 2 1 - Set i/p mode for device 

input intin (0)=Logical input device to request or sample, 

mode l=locator, 2=valuator (locator is mouse or 

3=choice, 4=string cursor keys) Intout 

vsin_mode intin (2)=input mode (l=req, 2=sample) shows mode selected. 


Input 28 

locator, 

request 

mode 

vrqjocator 


110 1 - Return position of 

ptsin (0)=initial x coor intout(0)= locator device, 
ptsin (2)=initial y coor terminate Screen tracks cursor 
ptsout(0)=final x coor character till terminated by 

ptsout(2)=final y coor (LSByte) key/button press 


Input 

locator, 

sample 


28 1 1/0 0 0/1 
ptsin (0)=init x coor 


intout(0)= 

terminate 


Return position (NDC) 
of locator device 
If set o/p's 


mode 

ptsout(0)=new x coor character 

new coor 

T 

““ IT 

(cursor 

ptsout(2)=new y coor (LSByte) 

key press 

0 

1 

change/ 

(A tablet or a mouse terminate 

no i/p 

0 

0 

event) 

characters begin at 20H, 32dec) 

key press & 



vsmjocator 

If 2 locators, either may input 

new coor 

1 

1 


Input 29 

0 0 12 

Return value of 

valuator. 

in tin (0)=initial value 

valuator device. 

request mode 

intout(0)=output value 

arrow keys, range 

vrq_valuator 

intout(2)=terminator 

1 to 100. 


Input 29 
valuator, 
sample 
mode 

vsm valuator 


0 0 10/2 
intin (0)=initial value 
intout(0)=new valuator value 
intout(2)=keypress, if event 

occured 


Return value of 


valuator device. 

cntrl $8 

event 

0 

nothing 

1 

val change 

2 

key press 
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Input functions (Not implemented) cont. 


Pointpair Integers Device 

Function Op in out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 


Input 30 
choice, 

request mode 
vrcj_choice 


0 0 11 
intin (0)=lnitial choice number 
(range 1 to device - Atrari ST 10 - 
dependent maximum) 
intout(0)= terminator key (1-10) or 


Return choice status 
of device chosen. 

If invalid return 
choice number 
ASCII code 


Input 30 
choice, 
sample mode 
vsm choice 


0 0 0 1 
intout(0)=0, choice number (1 to 10) 
cntrl $8=0, nothing occured 
=1, sampled o'k 


Return choice status 
of device chosen. 
intout(0)=0 if 
unsuccessful. 


Input 31 

string, 
request 
mode 

vrq_string 

1 0 2 L 

ptsin (0)=screen x coor L=array 

ptsin (2)=screen y coor length 

intin (0)=maximum string length 
intin (2)=0, no echo 

1, echo at ptsin 

Input 31 

1020/0 

string 

ptsin (0)=screen x coordinate 

sample 

ptsin (2)=screen y coordinate 

mode 

intin (0)=max string length (absolute) 


intin (2)=0, no echo 


1, echo at ptsin 

vsm_string 

cntrl(8)=0, no characters returned 


Return a string from 
specified device. 
Terminate on CR 
or intout full. If 
intin(0) is negative 
pg D4 defines keyboard 

Return a string from 
specified device. 
Terminate on CR, 
intout full or 
no more data. If 
intin(0) is negative 
pg D.4 defines keyboard. 
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Inquire functions 

The inquire functions return the current attribute settings of a specific device. 


Pointpair Integers Device 

Function Op in out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 

Extended 102 0 6 1 45 - Return extra device 

inquire intin (0) =0 open workstation values information not in the 

function =1 extended inquire open workstation call or 

intout(O) =0 not screen return open workstation 

=1 separate screen \ Alpha & values. 

=2 common screen / graphics 

=3 separate image mem \Common alpha & 

=4 common image mem / graphic controller 
intout(2) =# pallette background colours (may not be same 

intout(4) =Text effects supported (op 106) as $4E(78) 

intout(6) =Scaling 0=no 1= yes v_opnwk 

intout(8) =Number of planes 
intout($A) =Support lookup table 0=no l=yes 
intout($C) =# 16x16 pixel raster operations/sec (Speed factor) 
intout($E) =Contour fill capability 0=no l=yes 
intout($10) ^Character rotate 0=no, 1=90' steps only, 2=cont. 
intout($12) =# writing modes available 
intout($14) =Input mode 0=none, l=request, 2=sample 
intout($16) =Text alignment 0=no, l=yes 
intout($18) =Inking ability 0=no, l=yes (Plotter - colour pen) 
intout($lA) =Rubberbanding 0=no, l=lines, 

2=lines & rectangles (Printer - colour ribbon) 
intout($lC)=Maximum ptsin -l=no max 
intout($lE) =Maximum intin -l=no max 
intout($20) =Number of keys on mouse 
intout($22) =Styles for wide lines 0=no, l=yes 
intout($24) = Writing modes for wide lines 
intout($26-$58) reserved, contains zero words 
vq_extnd ptsout(0-$16) reserved, contains zero words 


4.22 





GEM VDI 



Inquire function cont. 


Function Op 
$0 

Pointpair Integers Device 

in out in out GDP name Comments 

$2 $4 $6 $8 $A $C 



26 


0 0 2 4 - Return value of colour 

intin (0)=request colour index index in RGB units 

intin (2)=0_return colour value request 

l_return colour values available Intout(0)=-1 'out 
intout (0)=colour index of range' 

intout(2)=red intensity (0-1000) 
intout(4)=green intensity (0-1000) 
intout(6)=blue intensity (0-1000) 


Inquire 
colour 
representation 


vq_color 


Inquire 35 
current 
polyline 
attributes 

vql_attributes 


0 10 5 - Return all attributes 

ptsout(0)=line width that affect polylines 

ptsout(2)=zero 

intout(0)=line type intout(6)=Start end style 
intout(2)=line colour intout(8)=Finish end style 
intout(4)=write mode 


Inquire 36 
current 
polymarker 
attributes 

vqm_attributes 


0 10 3 

ptsout(0)=width 
ptsout(2)=height 
intout(0)=marker type 
intout(2)=marker colour 
intout(4)= writing mode 


Inquire 37 
current 
fill area 
attributes 

vqfjittributes 


0 0 0 5 

intout(0)=interior style (Op #23) 
intout(2)=colour 
intout(4)=fill style (Op #24) 
intout(6)=writing mode (Pg 4.13) 
intout(8)=fill perimeter status 


Return all attributes 
that affect polymarkers 


Return all attributes 
that affect fill areas 
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Inquire function cont. 


Function Op 
$0 

Inquire 38 
current 
graphic 
text 

attributes 


vqt_attributes 

Inquire 116 

text 

extent 


vqt_extent 


Pointpair Integers Device 

in out in out GDP name Comments 

$2 $4 $6 $8 $A $C 

0 2 0 6 - Return all attributes 

ptsout(0)=character width that affect 

ptsout(2)=character height graphic text. 

ptsout(4)=cell width 

ptsout(6)=cell height 

intout(0)=current graphic text face 

intout(2)=current graphic text colour 

intout(4)=baseline angular rotation (0-3600) 

intout(6)=horizontal alignment 

intout(8)=vertical alignment 

intout($A)=writing mode (op #32 Pg 4.13) 

0 4 n 0 - Return a rectangle 

intinO = # words in text (low bytes) that encloses the 
ptsout(0)=x coordinate \ bottom specified string. 

ptsout(2)=y coordinate / left 

ptsout(4)=x coordinate \ bottom 

ptsout(6)=y coordinate / right 

ptsout(8)=x coordinate \ top 

ptsout($A)=y coordinate / right 

ptsout($C)=x coordinate \ top 

ptsout($E)=y coordinate / left 


Y axis 



Inquire 1170 3 1 1 - Return the character cell 

character intin (0)=character value in ADE form width for specified 

cell ptsout(0)=cell width ptsout(2)=0 character in current 

width ptsout(4)=left char delta ptsout(6)=0 text face. 

ptsout(8)=right char delta ptsout($A)=0 Rotation and special 
vqt_width intout(0)=ADE of inquire value affects ignored. 

-1 if invalid character 


Inquire 130 0 0 1 33 

face name intin (0)=element number 

and index intout(0)=ID number 

vqt_name intout(2-$40) 32 ADE code 

(lowbytes) 


Return 32 character face 
descriptor (text). 

First 16 characters face 
Second 16 style and weight 
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Inquire function cont. 


Function Op 
$0 


Inquire 27 


return 

return 

return 


vq_cellarray 


Inquire 115 
input 
mode 
vqinjmode 


Inquire 131 

current 

face 

information 


Pointpair Integers Device 

in out in out GDP name Comments 

$2' $4 $6 $8 $A $C 


2 0 0 n - Return cell array 

cntrl $E=row length \colour index definition of pixels 

cntrl $10=# rows / array 

cntrl $12=# elements/row \used in colour 

cntrl $14=# rows /index array 

cntrl $16=errors, 0=no errors, l=pixel colour indeterminate 

ptsin (0)=x coor ptsin (2)=y coor (lower left) 

ptsin (4)=x coor ptsin (6)=y coor (upper right) 

intout colour index array (1 row at a time) 

-1 indicates indeterminate pixel colour 


0 0 11 - Return current i/p 

intin (0)=logical device mode for device. 

l=locator 2=valuator 3=choice, 4=string 
intout(0)=i/p mode l=request, 2=sample 


0 5 0 2 - Return current face 

ptsout(0)=maximum normal cell width size information. 
ptsout(2)=baseline to bottom 
ptsout(4)=maximum extra skew width 
ptsout(6)=baseline to descent line 
ptsout(8)=left skew extra see pg 4.26 

ptsout($A)=baseline to half distance 
ptsout($C)=right skew extra 

ptsout($E)=baseline to ascent ADE= ASCII 

ptsout($10)=zero decimal 

ptsout($12)=baseline to top distance equivale 

intout(0)=first character \ in face 

intout(2)=last character / ADE 
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GEM VDI 


Escape functions 


The escape functions allow the programmer to access special device 
functions. 


Function Op 
$0 

Pointpair Integers Device 

in out in out GDP name 
$2 $4 $6 $8 $A $C 

Comments 

Escape 5 

(General format) 

id 



Inquire 5 

addressable 

alpha 

character cells 
vcj_chcells 

0 0 0 2 1 - 
intout(0)=# rows 
intout(2)=# columns 

-1 no cursor addressing 

Get number of vertical 
rows and horizontal 
columns for alpha 
cursor. 

Exit 5 

alpha mode 
v_exit_cur 

CN 

O 

o 

o 

o 


Enter graphics mode 
and exit alphanumeric 
mode. 

Enter 5 

alpha mode 
v_enter_cur 

0 0 0 0 3 - 

cursor set to upper left of character cell 

Exit graphics mode 
and enter 

alphanumeric mode. 

Alpha 5 

cursor up 
v_curup 

0 0 0 0 4 

Do nothing if at top 


Move alpha cursor 
up one row. 

Alpha 5 

cursor down 
v_curdown 

0 0 0 0 5 

Do nothing if at bottom 


Move alpha cursor 
down one row 

Alpha 5 

cursor right 
v_curright 

0 0 0 0 6 
Do nothing if at right edge 


Move alpha cursor 
right one column. 

Alpha 5 

cursor left 
v_curleft 

0 0 0 0 7 

Do nothing if at left edge 


Move alpha cursor 
left one column. 

Home 5 

alpha cursor 
v_curhome 

0 0 0 0 8 
Home usually top left 


Move cursor to 
home position. 
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Escape functions cont. 

Function Op 
$0 

Pointpair Integers Device 

in out in out GDP name 
$2 $4 $6 $8 $A $C 

Comments 

Erase to 5 
end of 
alpha screen 
v_eeos 

0 0 0 0 9 - 

No cursor position change 

Erase from current 
cursor position 
to end of screen. 

Erase to 5 
end of 

alpha text line 
v_eeol 

0 0 0 0 10 - 
No cursor position change 

Erase from current 
cursor position to 
end of line. 

Direct 5 

alpha cursor 
address 
vs_curaddress 

0 0 2 0 11 - 
intin (0)=row (1 to n) 
intin (2)=column (1 to n) 

Place cursor at the 
specified row and 
column. 

Output 5 
cursor 
addressable 
alpha text 
v_curtext 

0 0 n 0 12 - 

n=number of characters in string 

intin ()=text string in ADE 

Display a string of 
alpha text from 
current cursor 
position. 

Reverse 5 
video on 
vjrvon 

0 0 0 0 13 - 

Display following 
text in reverse video. 

Reverse 5 
video off 
v_rvoff 

O 

o 

o 

o 

Display following 
text in normal video. 

Inquire 5 
current 
alpha cursor 
address 
vcj_curaddress 

0 0 0 2 15 - 

intout(0)=row# (minimum one) 
intout(2)=column# (minimum one) 

Return current 
alpha cursor 
position. 
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Escape functions cont. 

Function Op 
$0 

Pointpair Integers Device 

in out in out GDP name 
$2 ' $4 $6 $8 $A $C 

Comments 

Inquire 5 

tablet 

status 

vqjabstatus 

0 0 0 1 16 - 
intout(0)=0 / not available 
-1, available 

Return availability 
status of tablet, 
mouse, joystick etc. 

Hard 5 

copy 

vjiardcopy 

l 

IN 
r— 1 

o 

o 

o 

o 

Copy screen to 
specific printer. 

Place 5 

graphic 
cursor at 
location 
v_dspcursor 

2 0 0 0 18 Place crosshair 

ptsin (0)=x coordinate on screen, 

ptsin (2)=y coordinate 

The positioning function is not accurate 

Remove 5 
last graphic 
cursor 
v_rmcursor 

0 0 0 0 19 - 
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Escape functions (Not implemented) 


The following Escape functions are available when loaded via the expanded 
GDOS file, they are included for completeness; as is a discussion on VDI bit 
image file format. 


Pointpair Integers Device 


Function Op 
$0 

in out in out GDP name 

$2 $4 $6 $8 $A $C 

Comments 

Form 5 

advance 

v_form_adv 

0 0 0 0 20 - 

Pages printer but 
keeps screen display 

Output 5 2 0 0 0 21 - 

window ptsin (0)=x coordinate Window 

ptsin (2)=y coordinate / corner 
ptsin (4)=x coordinate \opposite 
v_output_window ptsin (6)=y coordinate / corner 

Copies specified 
window to printer 
Adjacent pictures 
may not join. 

Clear 5 

display list 
v_clear_disp_lis 

0 0 0 0 22 - 

Empty the VDI 
printer buffer 

Output 5 
bit 

image 

file 

v_bit_image 

0-2 0 L+2 0 23 Enables printer 

cntrl (2) =0, get coordinates from file to process bit 

=1, upper left specified image file. 

=2, user specified coords Page placement 

ptsin (0)=x upper left \ coordinates by specifying 

ptsin (2)=y upper left 1 if or by default 

ptsin (4)=x lower right i specified 

ptsin (6)=y lower right / Pixel ratio 

intin (0)=Aspect ratio flag provides for 

0_ignore, l_pixel ratio, 2_page ratio printing 

intin (2)=Scaling 0_uniform, l_x and y circles 

in tin (4)=First character of file name (length L) 
intin (2n+2)=Last (nth) character file name 

Select 5 

palette 

vs_palette 

0 0 1 1 60 - 
intin (0)=0_use red, green, brown 
=1, use cyan, magenta, white 
intout(0)=palette selected 

Allows IBM 
compatable 
palette 
selection. 
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Escape functions (Not implemented) 



Pointpair Integers Device 


Function 

Op 

in ■ out in out GDP name 

Comments 


$0 

$2 $4 $6 $8 $A $C 


Inquire 

5 

0 0 0 125 91 - 

Return film driver 

palette 




film types 


intout 5 sets of 25 ADE byte descriptor strings 

vcjpjilms 




Inquire 

5 

0 0 0 20 92 - 

Return film driver 

palette 


intout(0)=port # 0=first comms port 

status block. 

driver 


intout(2)=film number (0 to s) 


state 


intout(4)=lightness control(-3 +3) 1/3 f_stop steps 



intout(6)=0 noninterlace, 1 interlace 




intout(8)=planes(l to 4) 

(ADE format) 

vqp_state 


intout($0A-$28)=colour codes for 16 colours. 

Set 

5 

0 0 0 20 93 - 

Set film driver 

palette 


intout(0)=port # 0=first comms port 

status block. 

driver 


intout(2)=film number (0 to 4) 


state 


intout(4)=lightness control(-3 +3) 1/3 f stop steps 



intout(6)=0 noninterlace, 1 interlace 


vsp_state 


intout($8-$26)=color codes for 16 colors 


Save 

5 

l 

CJ> 

o 

o 

o 

o 

Save current 

palette 



driver state to 

driver state 


disk 

vsp_save 




Supress 

5 

0 0 0 0 95 - 

Supress user 

palette 



prompts and error 

messages 



messages 

vsp_message 
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Escape functions (Not implemented) cont. 


Pointpair Integers Device 

Function Op in out in out GDP name Comments 

$0 $2 $4 $6 $8 $A $C 

Palette 5 6 0 0 1 96 - Return error code 

error intout(O) =0, no error 

inquire =1, open dark slide for print film 

-2, no port at specified location 

=3, palette not found at port specified 

=4, video cable disconnected 

-5, OS does not allow memory allocation 

-6, not enough memory for buffer 

=7, memory not deallocated 

=8, driver file not found 

=9, driver file incorrect type 

vqp_error =10, prompt user to process print film 

Update 5 2 0 0 0 98"""” Update'fife 

metafile ptsin (0)=min x value \ header enabling 

extents ptsin (2)=min y value I bounding application to 

ptsin (4)=max x value I rectangle get indication of 

v_meta_extents ptsin (6)=max y value / a minimum window. 


Write 5 n 0 1 0 99 - 

metafile ptsin user defined data 

item intin user defined data 

intin(0)=sub-opcode 

v_write_meta Sub opcodes 0 to 100 reserved 


Intin and ptsin 
data written to 
metafile with a 
sub opcode >100 
see pages 4.35 to 4.36 


Change 5 0 0 1 0 100 - Rename metafile 

GEM VDI intin ()=path/filename from GEMFILE. GEM 

filename upto 74 characters to ,GEM 

vmjilename 


Notation used for 
angular specification 
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Bit image file format 



There are two parts to the bit image 
Header file, a 16 word header, and a block of 

raw pixel data codified raw data. 


File header 


o 

2 

4 

6 

8 

10 

12 

14 

16 

18 

to 

32 


upper left x 
upper left y 
lower right x 
lower right y 
page width 
page height 
pixel widtn "1 
pixel height J 
bits per pixel 


Bit 

image 


in microns 


Source 

device 


Zero, reserved 


Raw data formats 


The four methods of data coding may be mixed in any desired combination 
within a file. 


Run length encoding (default) 


$oo 

$01 


<128bvtes 


<256 


$00 

$01 

$02 


-1 


<128bvtes 


<256 


Run length Use a two hyte subheader to define 

colour index data the data, which must be less than 128. 
The pixels may line wrap. 

Extended run length encoding 

Op code To cater for pixel runs >127, the 

extended run length extended run includes a count of 128 
colour index data providing a range of 128 to 255 pixels. 
The pixel line may wrap. 
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Raster encoding 


$oo' 

$01 

$02 


-2 


Op code 

# pixels in stream 
packed colour indices 


00 01 10 11 0001011001010 
0 11 I 


Raster encoding 
packs color indices into 
bytes in the following 
format: 


Pixels 

Bits 

Bytes 


Use either: 

1 (black and white) 

3 (four colour) 

or 4 (sixteen colour) 

bits per pixels format (offset $10 in the header). 


Raster run encoding 



Op code 
repeat count 
# pixels in stream 

packed colour indices 


Raster run encoding permits 
the efficient coding of repeated 
pixel patterns. It is in the same 
form as raster encoding but 
includes a repeat count in the 
header. 
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Metafile Sub opcodes 

The Metafile functions are not implemented on the Atari ST, but are included 
for completeness of the GEM operating environment. Installation of the file 
Meta.sys will provide the functions, if you can get it? 


Output page (Not implemented) 

There are two reserved GEM output codes for configuring the output page: 

Physical page size, which defines the output area and Coordinate window, 
specifying the coordinate system used in the metafile. 


Function 

Op 

$0 

Pointpair Integers 
in out in out 

$2 $4 $6 $8 

Device 
GDP name 
$A $C 

Comments 

Physical 

page 

size 

5 

0 0 3 0 

intin (0)=sub opcode C 
intin (2)=page width 
intin (4)=page height 

99 - 

) 

\ tenths of 
/ millimeters 

Sub opcode 0 


Coordinates 0 0 5 0 99 - Sub opcode 1 

window intin (0)=sub opcode 1 

intin (2)=x coordinate \ lower left corner 
intin (4)=y coordinate / of window 
intin (6)=x coordinate \ upper right corner 
intin (8)=y coordinate / of window 
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Metafile sub opcodes (Not implemented) cont. 

GEM Draw 

There are a number of reserved GEM output codes used by GEM draw: 
Group: Start and end enclose a set of primitives. 

Draw area type primitive: Start and end indicate that enclosed functions are 
subject to the area type primitive block that follows the start function. 

Attribute shadow: On and off indicate enclosed primitives are ignored as they 
are used to draw a drop shadow for the first primitive following 'off' . 

Set no line style: Subsequent area type primitives are not outlined. 


Function Op 
$0 

Pointpair Integers 
in out in out GDP 

$2 $4 $6 $8 $A 

Device 

name 

$C 

Comments 

Start 5 

group 

0 0 1 0 99 

intin (0)=sub opcode 10 


Bracket a set of 
primitives as a 
group for a 

End 5 

group 

6 6 1 0 99 

intin (0)=sub opcode 11 

- 

GEM DRAW 
application 

Start draw 5 
area type 
primitive 

6 0 1 0 99 

intin (0)=sub opcode 80 


Use the vertices 
of the first 

primitive (except text) 

End draw 5 
area type 
primitive 

0 0 1 0 99 

intin (0)=sub opcode 81 


to define a 
GEM DRAW area 
type primitive. 

Set 5 

attribute 
shadow on 

6 6 1 0 99 

intin (0)=sub opcode 50 


Only draw a drop 
shadow on the first 
primitive, ignore 

Set 5 

attribute 
shadow off 

6 6 1 0 99 

intin (0)=sub opcode 51 


remaining shadow 
primitives until next 
off sub-opcode. 

Set no 5 

line style 

6 0 1 0 99 

intin (0)=sub opcode 49 


Subsequent area 
type primitives 
not to be outlined 
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GEM AES function calls 


A set of application environment services (AES) function calls are available to 
the programmer, they consist of routines that make extensive use of the VDI 
function calls, and a dispatcher that provides a limited multitasking capability. 
The GEM VDI calls generally manage graphic outputs to peripheral devices, 
screen, printer etc. whereas GEM AES calls usually handle graphics input. The 
calls are grouped into eleven libraries that provide a variety of facilities: 

Application library: controls the access to the other AES libraries. 

Event library: responds to user inputs from mouse, keyboard or elapsed time. 
Menu library: text options. 

Object library: data collections that describes a displayed object, eg a box, an 
icon. 

Form library: a means of obtaining information by the use of a list of questions. 
Graphics library: a set of routines for manipulating the outline of a rectangular 

Scrap library: routines that allow the interchange of data between applications. 
File selector library: user selection of a file from a displayed directory or a file 
via a filename and path. 

Window library: manages up to eight GEM AES windows. 

Resource library: provides the interface between the application and its data and 
files. 

Shell library: enables an application to invoke another application and to keep 
track of the calling command and tail. 


Within GEM AES there is a limited multitasking environment created by the 
dispatcher; a routine that activates processes sequentially simulating a 
multitasking environment. The dispatcher maintains two process queues, the 
'ready' for processing list and the 'not ready' list, where processes are typically 
waiting for a user input, an input from another process or a specified time delay. 
Each 'ready' process is allowed a predefined period of CPU time before being 
returned to the end of the 'ready' queue, the environment is saved, the queues 
updated and control passed to the next item in the 'ready' queue. 

Access to the AES functions is through an extended BDOS call and the AES 
parameter block (six longword pointers to the tables; cntrl, global array, input 
and output attributes and input and output addresses). The AES parameter 
block, control table and global array have the following formats: 
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GEM AES 


AES parameter block 


$00 

Control 
table pointer 

C0n,r01 Controllable 

$04 

Global 

nlnhal 


$08 

array 

I/P attribute 
table pointer 

$00 

$02 

int_in 

Od code 
Length of i/p 
coordinate table 

$0C 

O/P attribute 
table pointer 

$04 

int_out 

Length of o/p 
coordinate table 

$10 

I/P addlress 
table pointer 

. , $06 
addrjn v 

Length of i/p 
address table 

$14 

O/P address 
table pointer 

addr_ou$ 08 

Length of o/p 
address table 

$18 


$0A 



Table 

length 

in 

words 

Table 

length 

in 

longwords 


Global array 

$00 1 version 0 GEM AES version identification word 

$02 count 2 Max # concurrent applications supported 

$04 id 4 Unique application identifier 

$06 private 6 Longwora user data as required 

$0A ptree ~~ 1 0 Pointer to resource load address tree, initially zero 

$0E reserved 14 Zero, address of memory allocations 

$12 reserved 18 Zero, memory length, screen colours 

$16 reserved 22 Zero 

$1 A reserved 26 Zero 

$1 E l 30 

The minimum size of an input table is one word, which must contain zero if 
no parameters are being passed. 
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Typical AES application call 

A typical sequence of calls for an application might be: 

a) Initialize and free unused memory, set up GEM parameter blocks and 
tables APPL_INIT [10] must be called first). 

b) Open (virtual) workstation and get the screen resolution, . 

c) Load a resource file, applicable to the current screen resolution and 
number of colours available, into memory. 

d) Get the address of specific resource objects and store them in memory. 

e) Get the address of the resource menu bar and call 'display menu'. 

f) Find the size and location of window WIND_GET, identify window as a 
desktop (handle=0), get the windows width/height (get_field=4) and draw icons. 

g) Wait for a user action, a keystroke, mouse button click or movement, GEM 
AES message or a specified time delay as either individual occurences or 
combined events. 

h) Select from the menu, normally by moving the mouse to the menu bar. 
The message buffer is updated automatically and the process waiting for the 
input is moved to the 'ready list' and progressed to the next stage. 

i) Reserve and then box a space to hold the dialog which is tested for an exit. 
On exit, any highlighting should be deselected. 

j) Further user selections, could entail keyboard entries, icon selection etc. 

...program... 

One of the first operations of an application is to create an active window, 
which may be sized, redrawn, updated and finally closed. 

Handles and coordinates 

Note that VDI calls use 'device' handles and AES 'window' handles - further 
confusion may arise in the use of 'file' handles - they are all different, beware !!!! 

The coordinate systems differ also ! 


y width 

xl.yl 

AES 

VDI 


x2,y2 


5.4 




GEM AES 


AES Parameter block sizes 

The numbers of parameters required by the various functions are detailed in 
the tabular format: 

Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

The table contains details of the parameter inputs and outputs; note that a 
zero indicates a block filled with a zero. 

GEM AES components 


Library 

Subroutines 


Monitor mouse 
movement and 
display error and 
system messages. 
Draw objects 


Resident in 
memory at 
all times 


Limited multitasking 
kernal and dispatched 


Dispatcher 


PRIMARY ’ 
APPLICATION 

word processor 
spreadsheet 
database etc. 


Up to six 

desk accessories 
Desk accessories run in a 
specially designed window 
on top of the GEM desktop 
or any other application 


Update 'ready’ and ’not-ready’ 
lists of the processes on each 
AES call. Use EVNT_TIME tc| 
ensure a sequencing if there 
are no AES calls. 


Desk accessory 
buffer 


Contains the .ACC 
files for the desk 
accessories. 

Up to 6, the files 
remain in memory 
until the user 
exits from AES. 


Screen manager 

Monitor mouse action 
when outside the 
work area. 


The screen manager 
handles all events in the 
border area of the top 
window, the menu bar 
and the drop down menus. 


Menu alert 
buffer 


Drop down menus 
and alert boxes always 
appear on top of a 
window, Icon or dialog. 
AES redraws these 
from this buffer when 
the menu is erased. 


Up to 1/4 screen 
capability and faster 
than an application 
redraw. 


Shell 


Runs on top of the limited 
multitasking kernal. 


Handles the passing of control 
from and to applications as 
they are called and terminated 
The shell also provides a 
graphic or text window as 
required by the application 
through a VDI open 
workstation call. 
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The GEM AES libraries 


Application library 

The application library functions initialize memory and data structures, 
terminate processes, communicate with other processes and record/replay user 
actions. 

Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

APPLJNIT 10 0 1 6 0 Initialize application and 

int_out(0)=application_ID generate data structures 

-1 failure, >=0 o'k prior to other AES 
placed in global array function calls. 

MUST call before any other AES function call 

APpLREAD 11 2 "l 1 6 Read n bytes from message 

int_in(0)=the 'from' pipe ID pipe. 

int_in(2)=number of bytes to read (n) 
int_out(0)=0_error, >0_o'k 
addr_in(0)=buffer address of the data to be read 

APPL_WRITE 12 2 1 1 6 Write n "bytes to message 

int_in(0)=the 'to' pipe ID pipe. 

int_in(2)=number of bytes to write (n) 
int_out(0)=0_error, >0_o'k 

addr_in(0)=buffer address of the data to be written 

APPLJFIND 13 0 1 1 0 Find the ID of another 

int_out(0)=application ID application in the system. 

=-l, not found 

addr_in(0)=address of a null The filename must be 8 

terminated filename characters long, blank fill. 
Handles SCRENMGR, CONTROL and EMULATOR may exist 
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Application library 

cont. 


Integers Addresses 


Function 

Op in out in out 

$0 $2 $4 $6 $8 

Comments 

APPL_TPLAY 

14 2 1 1 0 

Replay a series of user 

* 

int_in(0)=number of actions 
int_in(2)=speed(l-10000) 

actions. 


int_out(0)=one (always) 

speed 50=half 


addr_in(0)=address of memory 

100=full 


holding recording 

200=twice 


APPL_TRECORD 15 1 1 1 0 Record a series of actions 

* First word I low longword high 


(6 byte record int_in(0)=number of actions 0=timer elapsed time ms 

word-longword) int_out(0)=number recorded l=button O=up,l=down/#clicks 

addr_in(0)=address in memory 2=mouse x pixels / y pixels 

to Store records 3=keyboard char/keyboard_status 

APPL_EXIT 19 0 1 0 0 Let application library 

int_out(0)=0_error clean up environment when 

>0_o'k the appliction has finshed 

making calls 

It is possible to terminate an application with an illegal call 


* Note that functions APPL_TPLAY and APPL_TRECORD do not work on 
early ST operating systems (pre 'NEW TOS') 
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Event library 


The event library routines monitor multiple and individual user inputs 
providing efficient polling of the clock, keyboard, mouse and message pipes. 


Function 

Integers Addresses 
Op in out in out 

$0 $2 $4 $6 $8 

Comments 


EVNT_KEY 

20 0 1 0 0 
int_out(0)=keycode press 

Return standard keyboard 
code (Appendix D) 

EVNT BUTTON 21 3 5 0 0 

Return mouse status on 

* 

int in(0)=wait a #clicks 

button event 



int_in(2) ^buttmask 

Mask 

buttmask 

Keystate 


int in(4)=button state 

bit 0 

button left 

right shift 


int_out(0)=number clicks >=1 

bit 1 

2nd button 

left shift 


int out(2)=x coor \ on 

bit 2 

3rd button 

Ctrl 


int_out(4)=y coor / event 

bit 3 

up to 16 

Alt 


int_out(6)=button state 
int_out(8)=keystate 

Button state bits 0=up 

,l=down 

EVNT MOUSE 

22 5 5 0 0 

Return mouse status on 


int_in(0)=retum flag 

leaving specified area. 


int_in(2)=x coor \ area 
int_in(4)=y coor 1 position 

Return flag -1, on area exit 
=0, on area entry 


int_in(6)=width 1 pixel 

Mask 

Buttmask 

Kevstate 


int_in(8)=height / coordinate 

bit 0 

button left 

right shift 


int out(0)=Reserved (=1) 

bit 1 

2nd button 

left shift 


int out(2)=xcoor \ on 

bit 2 

3rd button 

Ctrl 


int out(4)=y coor / event 

bit 3 

up to 16 

Alt 


int_out(6)=button state 
int_out(8)=keystate 

Button state bits 0=up 

,l=down 
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Event library cont. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 


EVNT_MESAG 23 0 1 1 0 Rag message, up to eight 

int_out(0)=Reserved (=1) words, in message pipe. 


16 \ addr_in(0)=message type ID — * 

byte 1 addr_in(2)=ID of sender 

ID 

extra 

words 

Message 

function 

buffer/ addr in(4)=0 or length of 

10 

GH 

Selected menu 

message over 16 bytes 

20 

ABCDE 

Redraw window 

addr_in(6-14)=extra words 

21 

A 

Move work area to top 

Addr_in() extra word entries 

22 

A 

Close window 

A=windw_handi <o=ubject index title 

23 

A 

Toggle full size window 

B=x coor \ H=Object index item 

24 

AF 

Scroll/ page window 

C=y coor 1 active I=menu item ID 

25 

AJ 

Move window horizontally 

D=width 1 area (op#35 call return) 

26 

AJ 

Move window vertically 

E=height / J=top/left 0-1000 

27 

ABCDE 

Re-size window 

F=Page 0 up 1 down \Mouse 

28 

ABCDE 

Move window 

4_left 5_right 1 arrow 

29 

A 

Set new top window 

Row 2_up 3 down 1 click 

40 

I 

Desk accessory open mess 

. Column 6_left 7_right / message 

41 

I 

Desk_accessory close mess 

Messages entered FIFO, where message 

50 


ct update 

length >16 byte use APPL_READ. 

51 


ct move 

Reading kills a message. 

52 


ct_newtop 


EVNT_TIMER 24 2 1 

0 0 

Flag application that a 

int_in(0)=low 

\ longword 

specified length of time 

int_in(2)=high 

/ time ms 

has past. 

int_out(0)=Reserved (=1) 
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Event library cont. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

EVNT_MULTI 25 16 7 I 0 Application waiting on one or 

* int_in(0)=Standard key code more events. 

int_in(2)=number of clicks 

int_in(4)=buttmask Button state 0_up, l_down 

int_in(6)=button state 

int_in(8)=flags \Mouse Mask buttmask flags 

int_in($A)=x coor 11 bit 0 button left Keyboard 

int_in($C)=y coor I area bit 1 2nd button Button 

int_in($E)=width I event bit 2 3rd button Mouse 1 

int_in($10)=height / bit 3 Mouse 2 

int_in($12)=flags \Mouse bit 4 Message 

int_in($14)=x coor 12 bit 5 Time • 

int_in($16)=y coor I area 

int_in($18)=width I event Flags show the type of 

int_in($lA)=height / event the application is 

int_in($lC)=low \ longword waiting for or occurred 
int_in($lE)=high / time ms 

int_out(0)=flag Kevstate 

int_out(2)=x coordinate bit 0 right shift 

int_out(4)=y coordinate bit 1 left shift 

int_out(6)=button state bit 2 Ctrl 

int_out(8)=keystate bit 3 Alt 

int_out($A)=keycode press Retn standard keyboard code 

int_out($C)=number clicks >=1 # of button events / time 

addr_in(0)=16 byte buffer (see EVNT_MESAG op 23) 

EVNT”dCUCK 26 2 T 6” 0 GlV/serdoubTe dick 

int_in(0)=slow 0 to 4 fast speed 

int_in(2)=0_get, l_set 
int_out(0)=speed l_new 0_old 


* The 'NEW TOS' processes requests for single clicks correctly 
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Event Library cont. 

Most applications will wait for a combination of events using the 
EVNT_MULTI call. When a required event occurs, the application will be moved 
from the 'not ready' list to the 'ready' list by the dispatcher, respond to the event 
and then return to the 'not ready' list to wait for the next event in the 
EVNT_MULTI sequence. 

Be careful in using the right hand Atari mouse button if writing portable 
code, not all versions of GEM have two buttons. 

Keystroke selection 

Some menu items support keystoke selection through the EVNT_MULTI call. 
On receipt of the specified key selection, the application should call 
MENU_TNORMAL to highlight the title to enable the user to see the selection 
actually made; deselect highlighting when the application has finished with the 
menu. The 16-bit keyboard event codes are given in Appendix D; use 
GRAF_MKSTATE to decode Control, Alternate and left and right Shift keys. 

Icon selection 

The bits for the required icon selection sequence are set by the application in 
the EVNT_MULTI call, button up or down state and a predefined number of 
clicks within a given space of time. On the event taking place, a bit value for the 
mouse and keyboard state is returned; the application needs to also call 
GRAF_MKSTATE to obtain the mouse's x and y coordinates and then make an 
OBJC_FIND call passing the x and y coordinates and the address of the window, 
desktop or application object tree containing it's icons. 

If OBJC_FIND reports the mouse covering an icon, its state should be 
changed to selected. 

If the mouse does not cover an icon, the application should assume the user 
will select a group of icons by drawing an expanding rectangle around them. Call 
GRAF_MKSTATE to ensure the button is still depressed and then call 
GRAF_RUBBERBOX to provide the extent of the box when the button is released. 
The application should look for icons within the rectangle and change each icon 
from normal to selected via OBJC_CFIANGE calls. 
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Menu library 


The menu library routines provide the user with a textural menu choice from 
within an application, placing the mouse cursor over an enabled item and 
clicking the mouse button to make the selection. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

MENU_BAR 30 1110 Display/erase menu bar 

int_in(0)=menu bar 0_erase, l_draw 
int_out(0)=error 0_yes, +ve_no 
addr_in(0)=Object tree address that forms this menu 

MENU~_ICHECK 31 2 1 1 0 Display/erase menu item 

int_in(0)=menu item ID check mark. 

int_in(2)=0_clear, l_display (check mark) 
int_out(0)=error 0_yes, +ve_no 
addr_in(0)=Object tree address that forms this menu 

MENUJEN"AB"l~E 32 2 110 Disable /enable menu item 

int_in(0)=menu item ID 

int_in(2)=0_disabled, l_enabled (light/dark text) 
int_out(0)=error 0_yes, +ve_no 
addr_in(0)=Object tree address that forms this menu 

MEnUtNORMAL 33 2 1 1 6 Display menu title in 

int_in(0)=menu item ID reverse video. 

int_in(2)=0_reverse, l_normal video 
int_out(0)=error 0_yes, +ve_no 
addr_in(0)=Object tree address that forms this menu 

MENU_TEXT 34 i 1 2 0 Change text of menu item. 

int_in(0)=menu item ID reverse video. 

int_out(0) terror 0_yes, +ve_no 
addr_in(0)=Address of new text string for this item 
addr_in(4)=Object tree address that forms this menu 

MENUJ^GISTER 35 1110 Place desk accessory menu 

int_in(0)=Desk accessory item string on desk menu 

process ID and return acc's menu ID 
int_out(0)=menu item ID (0-5) 

addr_in(0)=address of desk accessory menu text string. 
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Menu library cont. 

To display a menu bar, call the resource function RSRC_GADDR with the 
menu bar's (object) details to obtain the long address of the object tree root, call 
MENU_BAR with the address and set the routine to draw. 


Menu bar control 

The AES screen manager controls all user interaction with the menu bar in 
the following manner: 

The user touches an item in the menu bar using the mouse cursor 

The screen manager receives a message that the cursor has entered the menu 
bar and enters the 'ready list'. It determines which item in the title bar the cursor 
touched, saves the screen under and displays the 'titles' menu; highlighting menu 
items as the cursor passes over them. 

The application is held in the 'not ready' list while the screen manager has 
initiated open menus. When the user clicks the mouse on a menu item, the screen 
manager sends details of the object tree of the menu selected to the primary 
application's message buffer. 

The dispatcher checks the 'not ready' list for the application process waiting 
for the message and moves it to the 'ready' list. 

The EVNT_MULTI call returns a flag of the events that occurred, which may 
be read by the application and any action deemed appropriate by the application 
taken. 

When the action is complete, the menu title is de-highlighted by the 
application making a MENU_TNORMAL call. 
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Object library 


An object, described by a collection of data in a linked list (object tree), can be 
created, deleted, edited, drawn on the screen, and the object's position on the 
screen found, using the object library routines. 

Object tree 

An object comprises of a parent and perhaps a number of different levels of 
children, who always reside within the parents display space. The tree is created 
by making seperate calls to the OBJC_ADD routine for each child or loaded from 
disk using RSRC_LOAD. 


Each child points to a 
brother in a chain, if it 
has one? The last one 
points back to its parent 

Different objects may 
be created by only 
using parts of the tree. 





Text 




o- 



Parent 
Child cl 

Child c2 
Child c3 


Boxtext type object 

Box type object 
Box type object 


— Parent - — 
cl — * c2 — * c3 
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The object library uses a number of additional tables, as well as the parameter 
block, control table and global arrays, to describe objects. The tables are accessed 
via the resource library routines and are as follows: 

Additional object library word tables 

(bracketed items are longwords) 



Object 


Iconblk 



Applblk 


offset 


Tedinfo 


Bitblk 



Parmblk 

(0) 

Nextchild 

\Text 

\Mask 

\ Image 

\Code 

\Tree 

(2) 

Firstchild 

/string 

/string 

/ pointer 

/ pointer 

/ pointer 

(4) 

Lastchild 

\Template \Data 

W_array 

\Loparm 

Objindex 

(6) 

Otype 

/string 

/string 

H_pixel 

/Hiparm 

Oldst 

(8) 

Oflag 

Wchar 

\Text 

x source 

- 


Newst 

($A) 

OState 

/pointer 

/string 

y_source 

- 


x coor 

($C) 

\OSpec 

Font 

Icon c 

fg colour 

- 


v coor 

($D) 

/ 

Reserved 

x_cpos 

0 


- 


W_pixel 

($10) 

x_coor 

Justify 

y_cpos 

- 


- 


H_pixel 

($12) 

y coor 

Colour 

x_ipos 

" 


- 


x epos 

($14) 

Width 

Reserved 

V ipos 

- 


- 


V epos 

($16) 

Height 

Borderthk 

i wide 

- 


- 


W cpxl 

($18) 


textlength 

i height 





H cpxl 

($1A) 


tmplength 

x_tpos 


Prefixes 


Loparm 

($1C) 

(x & y 


y_tpos 


0=object 


Hiparm 

($1E) 

relative to 


t wide 


c=character 


0 

($20) 

parent 


t height 


i=icon - 



($22) 

or screen) 


0 


t=text - 




The tables, filled by the object library routines, are used in performing 
various functions: 

Object: Provides data that describes each object, its tree relationship to other 
objects and its location relative to parent (screen if the root). The predefined 
object values on next page. 

Tedinfo: Allows object types Text (21), Boxtext (22), Ftext (29) and Fboxtext (30) 
to be edited, using the object table spec pointer to point to the Tedinfo table. The 
'NEW TOS' allows the underscore to be used in the text string. 

Iconblk: Is used to hold icon (31) data definitions. Object type Icon points here 
with its spec pointer. 

Bitblk: Object type Image (23) uses this to draw bit images like cursors and icons. 
Applblk: Is used to locate and call an application defined routine that draws and 
or cnanges an object. The object type Progdef (24) spec pointer points here. 
Parmblk: Storage of data used by the application defined routine above 
(applblk) and pointed to by the code pointer. 
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Object libraries cont. 

Routines which edit, create and draw data describing objects that appear on 
the screen: boxes, characters, icons etc. 

There are some predefined values for the table entries: 


Graphic types 
of objects 
(Otype) 


20=Box 

21=Text 

22=Boxtext 

23=Image 

24=Progdef 

25=Invisbox 

26=Button 

27=Boxchar 

28=String 

29=Ftext 

30=Fboxtext 

31=Icon 

32=Title 


Font types 

3=system font 
5=small font 


Ospec 

points 

to 

Object flags 
(Oflag) 

Object colours 
(color) 

- 

0x0000=none 

0=white 

Tedinfo 

0x0001 =selectable 

l=black 

Tedinfo 

0x0002=default 

2=red 

Bitblk 

0x0004=exit 

3=green 

Applblk 

0x0008=editable 

4=blue 

Nstrg 

0x001 O^rbutton 
0x0020=lastobj 

5=cyan 

6=yellow 

Nstrg 

0x0040=touchexit 

0x0080=hidetree 

7=magenta 

8=white 

Tedinfo 

0x0100=indirect 

9=black 

Tedinfo 

Iconblk 

Nstrg 

Colour fields 

10=lred 

ll=lgreen 

12=lblue 

13=lcyan 

14=lyellow 

15=lmagenta 


15 1211 8 

7 

6 4 

3 0 

border 

colour 

text 

colour 

0 trans 
1_replao 

“fill 
3 tvoe 

fin 

colour 


Object states 
(Ostate) 

0x0000=normal 

0x0001 =selected 

0x0002=crossed 

0x0004=checked 

0x0008=disabled 

0x001 0=outlined 

0x0020=shadowed 


Ospec 32-bit word/byte values 


Loword 

Highword 

Lobyte 

hibyte 

Box 

Invisbox 

Boxchar 

colour 

colour 

colour 

0 

borderthk 

0 

0 

0 

character 
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Editable text 

field definitions 

justification 

0=edstart 

l=edinit 

2=edchar 

3=edend 

(Justfy) 

0=left justified 
l=right justified 
2=centered 


Borderthk 

0 

none 

1 to 128 

inside 

-1 to -127 

outside 


(in pixels) 


9 

A 

a 

N 

n 

F 

P 


only digits 0 to 9 

only uppercase A to Z and space 

upper and lowercase A to Z and space 

0 to 9, uppercase A to Z and space 

0 to 9, upper and lowercase and space 

all valid DOS filename characters, plus ? * : 

all valid DOS pathname characters, plus \ : 

all valid DOS pathname characters, plus \ : 

anything 


Allowable valid 
characters 
(Vchar pointer) 


? 


* 
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Object library cont. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

OBJCADD 40 2 1 1 0 Add an object to an object 

int_in(0)=Parent ID tree. 

int_in(2)=Child ID (item to add) 

OBJC_DELETE 41 1110 Delete an object from an 

int_in(0)=Object to delete object tree. 

int_out(0)=error 0_yes / +ve_no 
addr_in(0)=Object tree address with object in it 


OBJC_DRAW 42 6 1 1 0 Draw an object in an 

int_in(0)=start object object tree. 

int_in(2)=draw 0_object only, nth level 

int_in(4)=x coordinate \ 

int_in(6)=y coordinate I Clip 

int_in(8)=width I rectangle 

int_in($A)=height / 

int_out(0)=error 0_yes, +ve_no 

addr_in(0)=Object tree address with object in it 

Ob)C_fTnD 43 4 "l I 6 Find an object under the 

int_in(0)=search start object mouse form. 

int_in(2)=levels of search 

int_in(4)=x coordinate \ mouse 

int_in(6)=y coordinate / location 

int_out(0)=-l_no object, 0 to n # of object in tree 

addr_in(0)=Object tree address of search start object 

6"BJC_OFFSET 44 i 3 1 6 Find objects screen relative 

int_in(0)=object to locate x and y coordinates 

int_out(0)=error 0_yes, +ve_no 
int_out(2)=x coordinate \ relative 

int_out(4)=y coordinate / to screen 

addr_in(0)=Object tree address with int_in(0) in it 
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Object library 

cont. 


Integers Addresses 


Function 

Op in out in out 

$0 $2 $4 $6 $8 

Comments 

OBJC_ORDER 

45 2 1 1 0 Reorder an object within a list 

int_in(0)=Object to be moved 

int_in(2)=new position (0_bottom level, l_next etc. to -1 top) 
int_out(0)=error 0_yes, +ve_no 
addr_in(0)=Object tree address with int_in(0) in it 


OBJC_EDIT 46 4 2 1 0 Edit object text. 

int_in(0)=text object to be edited 
int_in(2)=user input character 
int_in(4)=next character index in text string 
int_in(6)=0_reserved 

=l_format string using text and template strings 

=2_validate against Tedinfo valid_char, 
update and display. 

=3_turn off text cursor 
int_out(0)=error 0_yes, +ve_no 
int_out(2)=next character index after operation 
addr_in(0)=Object tree address of object with text in it 

OBJC_CHANGE 47 8 1 1 0 Changes an objects state 

int_in(0)=object to be changed value. 

int_in(2)=zero, reserved 

int_in(4)=x coordinate \ 

int_in(6)=y coordinate I Clip 

int_in(8)=width I rectangle 

int_in($A)=height / 

int_in($C)=object state new value 

int_in($E)=redraw 0_no, l_yes 

int_out(0)=error 0_yes, +ve_no 

addr_in(0)=Object tree address 


To display an icon, calculate the desktop windows work area using a 
WIND_GET call and use OBJC_DRAW to draw the icon in the work area. The 
icons position within the window is held by the Tconblk' structure. 
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Form library 


A set of routines that enable the user to reply to a list of questions, either by 
checking off boxes or entering text. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

FORMJDO 50 1 1 1 0 Monitor users interaction 

int_in(0)=object number with a form. 

int_out(0)=object number that caused the exit 
addr_in(0)=object tree address 

FORmIdTal’ 51 9 1 0 0 

int_in(0)=flag 
int_in(2)=x coordinate \ 
int_in(4)=y coordinate I small 
int_in(6)=width i box 

int_in(8)=height / 
int_in($A)=x coordinate \ 
int_in($C)=y coordinate I large 
int_in($E)=width I box 
int_in($10)=height / 
int_out(0)=error 0_yes, l_no 

FORM ALERT 52 1 1 1 0 Display an alert. 

int_in(0)=exit button 0=no default exit 

int_out(0)=chosen exit l=first exit button 

addr_in(0)=address of alert string 2=2nd exit button etc. 

FORM_ERROR 53 i 1 6 0 Display an error box 

int_in(0)=DOS error code 
int_out(0)=exit button code (as above) 


Reserve or free dialog box 
screen area. 

Hag: 

0=reserve screen space 
for dialog box 
l=draw expanding box 
2=draw shrinking box 
3=free screen space 


FORM_CENTER 54 0 5 1 0 

int_out(0)=one, reserved 
int_out(2)=x coordinate 
int_out(4)=y coordinate 
int_out(6)=width 
int_out(8)=height 
addrjn(0)=dialog object 


Centre a dialog box on the 
screen 

\Of 

I centered 
I object 
/ tree 

tree address 
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The forms library routines enable the user to respond to a typical printed 
style of form on the screen in a question and answer mode without tying up the 
applications resources. The forms library also provides a consistent 
application /user response format. The forms have three optional types of user 
response, they are: 

Check a single box. 

Check a combination of boxes. 

Provide a typed response; 

These may be used any number of times in any combination. Finally the user 
exits typically via an "o'k" or "cancel" button. 

Taking a dialog as an example: 

To display a dialog, which will appear in the centre of the screen, call 
resource function RSRC_GADDR to get the address of the dialogs object tree. Call 
FORM_DIAL to reserve screen space and then call OBJC_DRAW to draw the 
dialog. 

The application should call FORM_DO to monitor user interaction with the 
dialog box. Where user changes have been made, the application may use 
OBJC_CHANGE to reset initial values, in particular dehighlight selected buttons. 
It may also be necessary to save some changes made to dialogs. 

To exit from the dialog, call FORMJDIAL to release the screen space, the 
application which should be in an EVNT_MULTI wait state can redraw the 
screen using an OBJC_DRAW call. 

A nicer display may be achieved if FORM_DIAL is used to draw expanding 
and shrinking boxes on start up and finish of the dialog sequence. 

Edit keys 

Keys have certain specified meanings for editting the text fields of forms and 
dialog boxes: 

Left and right arrow: Move left or right within the field. 

Down arrow and tab: Move to first free space of the next field. 

Up arrow: Move to first free space of previous field. 

Delete: Delete character following cursor without moving cursor. 

Backspace: Delete character to the left of the cursor, move cursor and 
following text one space left. 

Return: End edit and terminate if either "o'k" or "cancel" type buttons are 
default objects, otherwise ignore. 

Escape: Clear all characters from the field. 
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Form library cont. 


Alerts 

Alerts, which are used by GEM AES to handle error conditions, contain one 
of three pictorial designs; note icon, wait icon and the stop icon, and up to a 
maximum of 5 lines of 30 character width text (each line being seperated by the 
" I " bar symbol) and up to 3 exit buttons, each containing up to 20 characters of 
text. 

A special case alert is the error box which reports errors in TOS terminology 
(appendix I). 

A typical set of object structures for an alert box with some textural 
information and "o'k" and "cancel" buttons might be: 

More than 30 characters /line could crash early TOS systems. 'NEW TOS' 
truncates the line and remains solid. 



Object 

structure 


"help" 

"o'k" 

"cancel" 

Comments 


element 

Box 

Text 

Boxtext 

Boxtext 

Pntr to next obj. 

0 

nextchild 

-1 

2 

3 

0 < — 

-1 root 

2 

firstchild 

1 

-1 

-1 

-1 

\ -1 lowest 

4 

lastchild 

3 

-1 

-1 

-1 

/ level 

6 

Otype 

Oflag 

Ostate 

20 

21 

22 

22 


8 

$A 

0 

0 

0 

0 

5 

0 

27 

0 

See page 5.16 
for details 

$C 

Ospec 

00020007L 0L 

0L 

0L 


$10 

x-coor 

90 Relative 86 

374 

374 


$12 

y coor 

150 to 

16 

18 

50 


$14 

width 

454 screen 

272 

64 

54 


$16 

height 

98 

64 

16 

16 




[ Relative to parent 

(Box)] 



The o'k button takes Oflag attributes selectable and exit. 

The cancel button takes Oflag attributes selectable, default, exit and lastobj. 
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Offset 

Tedinfo 

structure 

element Box 

"help" 

Text 

"o'k" 

Boxtext 

"cancel" 

Boxtext 

0 

Text string 

help 

o'k 

cancel 

4 

Tmplate string - 

0 

0 

0 

8 

Vchar pointer 

0 

0 

0 


Font 

3 

3 

3 

$D 

Reserved 

0 

0 

0 

$10 

Justify 

0 left 

2 center 

2 center 

$12 

Colour 

00020000L 

00020000L 00020000L 

$14 

Reserved 

0 

0 

0 

$16 

Borderthk 

0 

-2 

-2 

$18 

textlength 

0 

0 

0 

$1A 

tmplength 

0 

0 

0 


The form library follows the tree from root to children in displaying the form 
objects. 
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Graphics library 


The graphics library routines enable the programmer to manipulate the 
rectangular outline of a box. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

GRAF_RUBBERBOX 70 4 3 0 6 Draw a box that expands 

int_in(0)=x coordinate \ of and contracts from a fixed 

int_in(2)=y coordinate / box point as the mouse moves. 

int_in(4)=minimum pixel width 
int_in(6)=minimum pixel height 
int_out(0)=error 0_yes, +ve_no 
int_out(2)=width \ when button 

int_out(4)=height / last released 

G^F_DRAGBOX 71 8 ■ 3 6 6 Move a "box and keep the 

in t_in(0)= width \ Of mouse pointer at the same 

int_in(2)=height I box position inside the box. 

int_in(4)=x coordinate I being 

int_in(6)=y coordinate / dragged Height and width 

int_in(8)=x coordinate \ in pixels 

int_in($A)=y coordinate I Boundary 

int_in($C)=width I rectangle 

int_in($E)=height / 

int_out(0)=error 0_yes, +ve_no 
int_out(2)=x coordinate \ When button 


int_out(4)=y coordinate 

/ released 

GRAF_MOVEBOX 72 6 1 0 0 

int_in(0)=width 
int_in(2)=height 

Draw a moving box 

int in(4)=x coordinate \ 

Initial 

int in(6)=y coordinate / 

position Height and width 

int in(8)=x coordinate \ 

Final in pixels 

int_in($A)=y coordinate / 

position 

int_out(0)=error 0_yes, +ve. 

_no 
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Graphics library cont. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

GRAF_GROWBOX 73 8 1 0 6 Draw an expanding box 

int_in(0)=x coordinate \ outline 

int_in(2)=y coordinate I Initial 
int_in(4)=width I position 

int_in(6)=height / 
int_in(8)=x coordinate \ 

int _in($A)=y coordinate I Final Height and width 
int_in($C)=width I position in pixels 

int_in($E)=height / 
int_out(0)=error 0_yes / +ve_no 

GRAF_SHRINKBOX 74 8 1 0 0 Draw a shrinking box 

intjn(0)=x coordinate \ outline 

int_in(2)=y coordinate I Final 

int_in(4)=width I position 

int_in(6)=height / 
int_in(8)=x coordinate \ 

int_in($A)=y coordinate I Initial Height and width 
int_in($C)=width I position in pixels 

int_in($E)=height / 
int_out(0)=error 0_yes, +ve_no 

GRAF WATCHBOX 75 4 1 1 0 Track the mouse pointer 

int_in(0)=reserved and button inside and 

int_in(2)=object tree index outside the box. 

int_in(4)=in the box \ object 

int_in(6)=out of box / state 

int_out(0)=0_outside, l_inside the box 
addr_in(0)=address object tree containing box 

GRA"f_SLIDEBOX 76 3 1 1 0 Keep sliding box inside 

int_in(0)=parent index parent box. 

int_in(2)=object index (slider) 
int_in(4)=motion 0_horizontal, l_vertical 
int_out(0)=0_left/ top to 1000_right/bottom 
addr_in(0)=Address of object tree containing slider & parent 
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Graphics library cont. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

GRAF”HANDrE~77"’o 5 6”””o 'Return GEM*' VDi'handTe’for 

int_out(0)=VDI handle open screen workstation. 

int_out(2)=width \ character cell 

int_out(4)=height / system font 

int_out(6)=wiath \ box for 

int_out(8)=height / system font 

GRArCMOUSE" 78 Y T 1 0 "PermirappYication to 

int_in(0) =0_arrow change predefined mouse. 

=l_text cursor (vertical bar) 

=2_bee (hourglass-IBM GEM) 

=3_hand with pointing finger 

=4_flat hand, extended fingers 

=5_thin cross hair 

=6_thick cross hair 

=7_outline cross hair 

=255_mouse form stored in addr_in(0) 

=256_hide mouse form 
=257_show mouse form 

int_out(0)=error 0_yes, +ve_no (VDI op 111) 

addr_in(0)=35 word buffer for mouse form definition block 

GRAF:MKSTATE'79"o‘ 5 6 6 Return current mouse location 

int_out(0)=l, reserved button and keyboard state. 

int_out(2)=x coor \mouse Mask Buttonstate keystate 

int_out(4)=y coor /location bit 1 butt left right_shift 

int_out(6)=Butonstate \ 0_up bit 2 2nd button left_shift 

int_out(8)=keystate /l down bit 3 3rd button Ctrl 

bit 4 Alt 


GEM AES provides the graphic routines to manipulate the rectangular 
outline of a box which are based on GEM VDI routines. Graphics applications 
should use GEM VDI directly for graphic output to avoid any loss in 
performance through the AES overhead. 
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Scrap library 

The scrap library consists of routines that manage the interchange of 
information between applications. Data is either deleted or copied from the 
source to the clipboard (disk file named scrap), which only holds one document; 
and then pasted (copied) from the clipboard (disk) to the target application. 


Function 


SCRP_READ 


SCRP_WRITE 


Integers Addresses 

Op in out in out Comments 

$0 $2 $4 $6 $8 

80 0 1 1 0 Read the current scrap 

int_out(0)=error 0_yes directory on the clipboard 

+ve_no 

addr_in(0)=buffer address into which 
scrap directory is copied. 

81 0 1 1 0 Write new scrap directory 

int_out(0) =error 0_yes to clipboard. (Cut & Copy) 

+ve_no 

addr_in(0)=buffer address from which 

scrap directory is copied to clipboard. 


The scrap data is held on disk in a file named scrap, the extension identifies 
the type of data: 

•txt ASCII text string 

-dif Spreadsheet data 

.gem Metafile - GEM VDI type graphic images 

.img Bit image - GEM VDI standard form 

Applications access the data via GEM BDOS file system calls to: 

Search 
Create a file 
Open a file 
Read a file 
Write a file 
Close a file 
Delete a file and 
Get file size. 
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File selector library 


The file selector library routine enables the programmer to select file from a 
displayed directory or to type in a filename and path. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

FS~EL_INPUT 90 6 2 2 6 Display file selector 

int_out(0)=error 0_yes box and monitor user 

+ve_no interaction with it. 

int_out(2)=exit button 0_cancel 
l_o'k 

addr_in(0)=buffer address of initial directory specification 
(If not updated holds last dir spec user selected) 
addr_in(4)=buffer address of initial selection displayed 
in file selector dialog box. 

(If not updated holds last selection) 


This routine displays a file directory dialog box, the user either selects a 
filename directly from the directory list using a mouse or types in a filename to 
create a new file. 

The file directory dialog box displays the name of the current directory path, 
a selection field, a scrollable directory listing and two buttons to terminate the 
routine. The user interacts with the dialog box in the standard manner, changing 
the directory being displayed, selecting an item from the directory list or typing 
in a user selection and then exiting via the "o'k" or "cancel" button. 

The file selector library returns the filename selected or entered, in the buffer 
at addr_in(4), the directory path of the file in the buffer at addr_in(0) and whether 
the selection is o'k or to be cancelled. The application acts upon the information 
as required. 

Entering the underscore into the directory string may cause older versions of 
the TOS to crash the ST. 
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Window Library 

The window library routines permit the creation, opening, closing and 
deletion of windows to a maximum of eight active windows. The window 
parameters can be recovered or set, the window under the mouse cursor found, a 
flag set to indicate that a window is being updated and the size of a window 
determined. 


Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

WINDCREATE 100 5 1 0 0 Allocate window size 

int_in(0)=window parts including border & return 

int_in(2)=x coordinate \ Of window handle. Window open 

int_in(4)=y coordinate I full must set size < = to that 

int_in(6)=width sizeallocated. 
int_in(8)=height/ window 

int_out(0)=window handle (-ve, no windows available) 

WIND_"OPEN 101 5 1 0 6 Open a window at it's 

int_in(0)=window handle initial size and location, 

int_in(2)=x coor \ - not necessarily it's 

int_in(4)=y coor I Window full size. 
int_in(6)=width I initial 
int_in(8)=height / size 
int_out(0)=error 0_yes, +ve_no 

WIND_CLOSE 102 1 1 0 0 Close window, "does not 

int_in(0)=window handle deallocate the window or 

int_out(0)=error 0_yes, +ve_no handle. 

WIND_DELETE 103 1 1 0 0 Free space occupied by 

int_in(0)=window handle window and handle. 

int_out(0)=error 0_yes, +ve_no 
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Window parts (bit representation) 


bitO 

Name (name and title bar) 


bit 1 

Close (close box) 


bit 2 

Full (full box) 


bit 3 

Move (move box) 


bit 4 

Info (information line) 


bit 5 

Size (size box) 


bit 6 

Uparrow (up arrow) 


bit 7 

Dnarrow (down arrow) 


bit 8 

Vslide (vertical slider) 


bit 9 

Lfarrow (left arrow) 


bit 10 

Rtarrow (right arrow) 


bit 11 

Hslide (horizontal slider) 



Window library cont. 


Integers Addresses 


Function 

Op in out in out 

$0 $2 $4 $6 $8 

Comments 

WIND GET 

104 2 5 0 0 

Get window data specified 


int_in(0)= window handle 

int_in(2)=get_field 

int out(0)=error 0 yes, +ve_no 

field 


int_out(2)= \ Data 

int_out(4)= 1 specified 

int_out(6)= 1 by Get 

int_out(8)= / field 


WIND SET 

105 6 1 0 0 

Set displayed window 


int_in(0)=window handle 
int_in(2)=set_field 
int_in(4)= \ Data 

int_in(6)= 1 specified 

int_in(8)= 1 by Set 

int_in($A)= / field 

int_out(0)=error 0_yes, +ve_no 

parameters 
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Get 

field (2) 

int out() 
(4) (6) 

(8) 

Associated function 

4 

x coor 

y coor 

width 

height 

Window work area 

5 

x coor 

y coor 

width 

height 

current \ size including 

6 

x coor 

y coor 

width 

height 

previous / border title 

7 

x coor 

y coor 

width 

height 

maximum poss window size 

8 

1-1000 

1 left, 1000 right 


relative horiz slider position 

9 

1-1000 

1 top, 1000 bottom 


relative vertical slider position 

10 

handle 




top window handle 

11 

x coor 

y coor 

width 

height 

first rectangle in window list 

12 

x coor 

y coor 

width 

height 

next rectangle in window list 

13 

reserved 





15 

1-1000 

(-1 default minimum sq box) 

relative horizontal slider size 

16 

1-1000 

(-1 default minimum 

sq box) 

relative vertical slider size 

17 





screen 


Set 

field (4) 

int in() 
(6) (8) 

($A) 

Associated function 

1 

Parts 

see pg 5.30 


window components 

2 

Name pointer 


address of name stmg 

3 

Info pointer 


address info line string 

5 

x coor 

y coor width 

height 

current window size 

8 

1-1000 

1 left, 1000 right 


relative horiz slider position 

9 

1-1000 

1 top, 1000 bottom 


relative vertical slider pos 

10 

handle 



top window handle 

14 

lo-word 

hi-word strtobj 


GEM desktop to draw 

15 

1-1000 

(-1 default minimum sq box) 

relative horiz slider size 

16 

1-1000 

(-1 default minimum 

sq box) 

relative vert slider size 

17 




screen 
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Window library cont. 


Integers Addresses 

Function 

Op in out in out Comments 

$0 $2 $4 $6 $8 

WIND_FIND 

106 2 1 0 0 Find window under mouse 

int_in(0)=x coordinate \ mouse 
int_in(2)=y coordinate / position 
int_out(0)= window handle 

WIND_UPDATE 107 1 1 0 0 Flag about to update window 

int_in(0)=update 0_end, l_begin (window locking) 

2_end, 3_begin (usual mouse control) 
int_out(0)=error 0_yes, +ve_no 

Do not alter size while update proceeding 

WINDCALC 

108 6 5 0 0 Ret window bordr/work area 

int_in(0)=area 0_work->-border, l_border->-work 
int_in(2)=parts (see pg 5.30 -same as window create) 
int_in(4)=x coordinate \ 

int_in(6)=y coordinate 1 border/work To calculate work 
int_in(8)=width 1 area values area, input border 

int_in($A)=height / area values. 

int_out(0)=error 0_yes, +ve_no To calculate border 

int_out(2)=x coor \ area input work 

int_out(4)-y coor 1 work/border area values, 

int out(6)=width 1 area values 


int_out(8)=height / 


Note that AES windows do not use the same coordinates as VDI 


AES x, y, width, height 
VDI xl,yl,x2,y2 
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The desktop window is always present in the AES environment and supports 
a maximum of eight windows at a time. The AES screen manager handles all the 
user interaction outside the border area and the sizing, dragging and scrolling 
actions requested from within the border. The contents of the border area 
determine which of these functions are available. 

Each user action sends a message through the message pipe to the 
applications 'EVNT_MESAG' buffer where it is stacked on a first in-first out 
basis. In order to perform the requested function, the message must first be read 
and then the window management action may be either programmed to be 
performed or ignored. The assembler GEM program (Appendix L) demonstrates 
the effect of creating a window with the facilities, but not incorporating any code 
to handle the screen managers requests. The example also shows the parts 
handled by the screen manager, moving sliders, rubber boxing windows etc. 

The application handles all activities within the window work area. 

To create a window, the application calls WIND_CREATE defining the type 
(only those facilities that the application supports) and position of the window 
required, returning the window handle to be used in all subsequent actions on 
the window. An application call to WIND_CALC may be used to return the size 
of the window work area. A call to WIND OPEN will get AES to draw the 
window's border area on the screen and send a message to the application to 
draw the windows work area. 

WIND_SET calls are used to set the size and location of the vertical and 
horizontal sliders. If the window is resized, the application must decide if the 
preview rubber box size is valid. If not, the application may resize to the nearest 
valid size or display a warning dialog message. If valid, the application must 
issue a WIND SET call to change the window size. A reduced window size does 
not require the work area to be redrawn, but if larger, GEM AES will send a 
message to the application to redraw the windows work area (EVNT_MESAG 
ID-20). 

The application is responsible for redrawing and updating the visible parts of 
its windows, which it divides into the smallest number of non-overlapping 
rectangles, found by a series of WIND_GET calls. Initially to the 'first' rectangle 
in the window list and subsequently to the 'next' rectangle until the returned 
width and height are both zero. Note that if the window is not covered, say by 
the control panel, that there will be only one rectangle. 
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Before updating the window, the application makes a WINDJJPDATE call 
to freeze all other rectangle lists and to prevent menus and alerts from being 
displayed during the update. On completion of the update, another 
WINDJJPDATE call permits further change to the display and rectangle lists. 

To redraw the window work area, each rectangle in the rectangle list is 
compared with the update rectangle in turn, and any common portion redrawn. 

To make a window active, the application (which must include an 
EVNT_MULTI call that includes a mouse button event) will receive a 'button 
pressed' message from the screen manager - the event occurred outside the active 
window and is therefore detected by the screen manager. The application calls 
WIND_FIND using the mouse x and y coordinates to obtain the handle of the 
window under the mouse. If it is the desktop, handle 0, a rubber box is drawn in 
expectation of the user selecting desktop icons. If the handle is that of an inactive 
window, the screen manager sends a message (EVNT_MESAG ID=29) to request 
the window be brought to the top. The application calls WIND_SET to comply. 

To close a window via the windows border or menu command, the screen 
manager sends a message to the application which should make a WIND_CLOSE 
call; a WIND_DELETE call will then free the handle. 
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Resource library 

The resource library provides the interface between the application and its 
file resources, trees, objects, icons and pictures etc. providing the means to port 
an application to a different environment by simply changing the resource file 
data. 


Function 

Integers Addresses 
Op in out in out 

$0 $2 k $4 $6 $8 

Comments 

RSRC_LOAD 

110 0 1 1 0 
int out(0)=error 0 yes, +ve no 

Allocate memory and load 
resource file into memory. 


addr_in(0)=ASCII filename string address 

RSRC_FREE 

t— ‘ 
t— i 

y— ‘ 
O 

O 

o 

Free the memory space 
allocated by rsrc_load. 


int_out(0)=error 0_yes, +ve_no 


RSRC_GADDR 112 2 10 1 Get address of data 


int_in(0)=type structure (object) 

int_in(2)=structure index loaded in memory. 

int_out(0) terror 0_yes, +ve_no 
addr_out(0)=address of specified structure 
Only functions with object types R_TREE and R_FRSTR 

RSRC_SADDR 113 2 1 1 0 Store the address of a 

int_in(0)=type data structure in memory. 

int_in(2)=structure location index 
int_out(0)=error 0_yes, +ve_no 
addr_in(0)=address of the data structure 

RSRC_OBFIX 114 1 1 1 0 Convert objects location 

int_in(0)=object index and size from character 

int_out(0)=l, reserved to pixels, coordinates 
addr_in(0)=object tree address 
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Type (of data structure) 


0 

tree 

8 

1 

object 

9 

2 

tedinfo 

10 

3 

icon blk 

11 

4 

bitblk 

12 

5 

string 

13 

6 

imagedata 

14 

7 

obspec 

15 

16 


text string (tedinfo) 

template string (tedinfo) 

valid chars (tedinfo) 

mask string (iconblk) 

data string (iconblk) 

text string (iconblk) 

image pointer (bitblk) 

pointer address of free string 
pointer address of free image 


To isolate an application from device, user and country specific data and 
provide program portability; GEM AES supports resource files that contain the 
variable parts of the application code. 

To use a resource file, the application makes a RSRC_LOAD call to find the 
total file size in bytes, allocate the memory space for the resource file and update 
the file for screen resolution. The pointers to the object and the tree structures are 
also updated and the address of the tree array stored in the applications 'Global 
array'. 

Access to the object library table pointers may be through RSRC_GADDR 
and RSRC_SADDR calls. The tree index may be accessed via FORM_DO and 
MENU_BAR calls among others. 

RSRC_FREE deallocates the resource file memory and zeroes the tree array 
address in the Global array. 

Resource files are generated using the Atari ST icon edit and resource utility 
program. 


5.36 




GEM AES 


Shell library 

The shell library routines enable one application to call another and keep 

track of command and command tails. 

Integers Addresses 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 

SHEL_READ 120 0 1 2 0 Let application identify 

int_out(0)=error 0_yes, command that called it in 

+ve_no format of GEM BDOS func 75 

addr_in(0)=buffer address of command string 
addr_in(4)=buffer address of command tail 

SHELJWRIT E 121 3 12 0 Inform GEM which, if any, 

int_in(0)=0_exit, l_run application to run or exit 

int_in(2)=graphic 0_no, l_yes GEM AES. 
int_in(4)=GEM application 0_no, l_yes 
int_out(0)=error 0_yes, +ve_no 
addr_in(0)=new executable command file address 
addr_in(4)=command tail address of next program 


SHEL_GET 

122 1 1 1 0 
int_in(0)=length 
int_out(0)=error code 
addr_in(0)=buffer address 

Read data from the 
GEMDOS environmental 
string buffer 

SHEL_PUT 

123 1 1 1 0 

int_in(0)=length 
int_out(0)=error code 
addr_in(0)=buffer address 

Write data to the 
GEMDOS environmental 
string buffer 


SHEL_FIND 124 0 1 1 0 Search for filename and 

int_out(0)=error 0_yes, return full DOS specification 

+ve_no 

addr_in(0)=address 80 character buffer minimum 
i/p search filename 
o/p full DOS filename 

SHEL ENVRN 125 0 1 2 0 Search for environment 

int_out(0)=l, reserved parameter and store 

address of following byte 
addr_in(0)=pointer to byte storage address 
addr_in(4)=search parameter string 
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The shell library routines use a single buffer containing the command and 
command tail that invoked the current application. A typical sequence to call and 
run another application might be: 

Call SHEL_WRITE with a command, command tail and the home directory 
addresses; also define graphic/character or GEM/Not GEM application. On 
completion of the current application, the shell library will start the requested 
application. 

Exit from GEM AES by making a SHEL_WRITE call with the int_in(0) 
parameter set to zero. 
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Chapter 6 


Intelligent keyboard commands 

General 6.2 

Keycodes 6.2 

Data packets 6.2 

Commands 6.3 

Reset 6.3 

Set mouse button action 6.3 

Set mouse relative position reporting 6.3 

Set mouse absolute positioning 6.3 

Set mouse keycode mode 6.3 

Set mouse threshold 6.3 

Set mouse scale 6.3 

Interrogate mouse position 6.3 

Load mouse position 6.4 

Sey y base position 6.4 

Set y base position at top 6.4 

Resume 6.4 

Disable mouse 6.4 

Pause output 6.4 

Set joystick event reporting 6.4 

Set joystick interrogation mode 6.4 

Joystick interrogation 6.4 

Set joystick monitoring 6.4 

Set fire button 6.4 

Set joystick keycode mode 6.5 

Disable joysticks 6.5 

Set time of day clock 6.5 

Interrogate time of day clock 6.5 

Memory load 6.5 

Memory read 6.6 

Controller execute 6.6 

Status inquiries 6.6 

Data packet functions 6.7 
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Intelligent keyboard commands 


General 

The Atari ST keyboard unit contains a 1MHz HD 6301 8-bit microprocessor 
with some on-board memory storage to maintain the time of day clock etc. The 
keyboard and its peripheral items, joystick and mouse may be initialized, 
monitored for position or status and the time of day clock read or set. 

The intelligent keyboard (ikbd) communicates with the main processor over 
a 7.8Kbit/s bidirectional serial link, sending individual keycodes or receiving 
instructions and returning status codes in packets of data through a pair of 
addresses, one for transmit and one for receive. 

Characters can be read from the keyboard input queue in main system RAM, 
it is filled by an interrupt routine that transfers data from the ikbd to memory 
automatically. Characters are written to the keyboard by placing the character 
code in the keyboard data register after bit 1 of the keyboard command/status 
register is set. 


Keycodes 

The keyboard transmits make and break keycodes for each key press and 
release. Appendix D provides the codes for the individual keys, bit 7 being set for 
break and cleared for make. 


Data packets 

To differentiate the keyboard codes from the data packets transmitted to and 
from the ikbd to the main processor; the codes #$F6 to #$FF precede status 
information packets. The packets provide reports of mouse position and status, 
time of day and joystick status. The packets may be stored and used later, with 
the header byte removed, to restore the condition of the ikbd. 
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Ikbd commands 


Input 
op code 
string 

Output 

databyte 

string 

Function 

#$80 

#$01 


Reset. Return keyboard to power-up status without 

affecting clock. A break 200ms also causes a reset 

#$07 

OOOOOaaa 


Set mouse button action, 
default %00000000 

bit 0 l_press \ Mouse position report on 

bit 1 1 jrelease / (only relevant in absolute mode) 

bit 2 0_button, l key type operation. 

#$08 


Set mouse relative position reporting (default). Position 

packet generated asynchronously 
when threshold exceeded 

#$09 
X msb 
X lsb 

Y msb 

Y lsb 


Set mouse absolute positioning. 

\ X maximum Resets ikbd x and y coordinates. 

/ The x and y values in 

\ Y maximum scaled mouse 'clicks' do 

/ not wrap, ignore <0 & >max 

#$0A 
X step 
Y step 


Set mouse keycode mode. Return mouse motion in cursor 

keycodes instead of relative or 
absolute motion records. 

#$0B 
X level 
Y level 


Set mouse threshold. Before move event is generated 

Default value 1 

(Relative motion only) 

#$0C 

X 

Y 


Set mouse scale. Set X and Y scale factors for 

absolute mouse positioning - 
'clicks' per coordinate change. 

#$0D 

#$F7 

OOOOxxxx 

X msb 
X lsb 

Y msb 

Y lsb 

Interrogate mouse position 

bit 0 right button down since last interrogation 

bit 1 right button up \ 

bit 2 left button down 1 since last 

bit 3 left button up / report 

\ X coor 

/ Only valid in absolute 

\ Y coor mode, regardless of mouse 

/ button action setting. 
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Ikbd commands 

cont. 

Input 
op code 
string 

Output 

databyte 

string 

Function 


#$0E 
#$00 
X msb \ 
X lsb / 

Y msb \ 

Y lsb / 


Load mouse position, 
filler (null) 

X coor \ in scaled 

1 coordinate 
Y coor / system 

Enables the user 
to preset the 
internal absolute 
mouse position 

#$0F 


Set Y = 0 at bottom 

Set for relative and 

#$10 


Set Y = 0 at top (default) 

absolute mouse motions. 

#$11 


Resume. 

Resume sending data back. 

#$12 


Disable mouse. Stop mouse event reports. Resume 

on any mouse mode command. 

#$13 


Pause output. 

Stop sending further reports, 
queue them in a (short) buffer. 

#$14 


Set joystick event reporting (default) 

#$15 


Set joystick interrogation mode. Disable joystick event 

reporting, use interrogate to 
sense joystick state. 

#$16 


Joystick interrogation. 

Return a record of current 
joystick state. 

#$17 

rate 

OOOOOOab 

aaaabbbb 

Set joystick monitoring, 
[packets of two bytes] 
bit 0 Joystick 1 \ Fire 
bit 1 Joystick 0 / button 

(sample rate of .01s) 

Set ikbd to monitor 
serial command line 
and joystick, update 


bits 0-3 Joystick 1 \ Position time of day clock 

bits 4-7 Joystick 0 / only 


#$18 cccccccc Set fire button monitoring Set ikbd to monitor serial 
packed 8- command line and fire button of 

bits/byte joystick 1, update time of day clock. 
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Ikbd commands cont. 

Input 

Output 



op code 

databyte 

Function 


string 

string 



#$19 


Set joystick keycode mode 

(Joystick 0) 

Rx 


(provides a velocity autorepeat facility) 

Ry 


initial rate final rate 


Tx 


Tn Tn Tn Vn Vn 

If Rn zero 

Ty 


| | | | | | |_ 

only Vn 

Vx 


1 < Rn > 1 times in .Is 

matters. 

vy 


length of time Directions x & y set individually. 

#$1A 

Disable joysticks. Disable any joystick event generation. 



Valid joystick commands resumes generation 

#$1B 


Set time of day clock 


YY 


year \ (86, 87, 88 etc) 

An invalid 

MM 


month 1 

BCD digit 

DD 


day 1 Data sent in packed 

does not 

hh 


hour 1 BCD format. 

alter the 

mm 


minute 1 

existing 

ss 


second / 

value. 

#$1C 

#$FC 

Interrogate time of day clock 



YY 

year \ 



MM 

month 1 



DD 

day 1 Data in returned in 



hh 

hour 1 packed BCD format. 



mm 

minute 1 



ss 

second / 


#$20 


Memory load 


Addr msb 


\ ikbd controller address 


Addr lsb 


/ to be loaded. 


Numb 


Number of data bytes (0-128) 


(data) 
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Ikbd commands cont. 


Input 
op code 
string 

Output 

databyte 

string 

Function 

#$21 

#$F6 

Memory read 

Addr msb #$20 

\ ikbd controller 

Addr lsb 

data 

/ address to be read. \ 


data 

1 6 bytes of 


data 

1 data starting 


data 

1 at address 


data 

1 (addr) 


data 

/ 


Status header 
memory access 


#$22 Controller execute Allows main system 

Addr msb \ ikbd controller to call an ikbd 

Addr lsb / subroutine address subroutine. 


OR 80 


Status inquiries. 


Get 8 byte data packet. Strip 

with the 

#$F6 




packet header and return to 

set 

mode 

#$7 #$8 

i #$9 

#$A #$0B #$0C 


recover 

command 

param 1 

Code 0 

Xmaxh 

Xstep XthreshXtick 

status 


param 2 

0 0 

Xmaxl 

Ystep YthreshYtick 



param 3 

0 0 

Ymaxh 

0 0 

0 




param 4 

0 0 

Ymaxl 

0 0 

0 


ONLY one 


param 5 

0 0 

0 

0 0 

0 


inquiry 


param 6 

0 0 

0 

0 0 

0 


at a 








time. 


#$F6 

Packet header 






mode 

#$0F #$10 #$12 #$14 #$15 


#$19 

#$1A 


param 1 

\ 

./ \ 

/ 


Rx 

on 


param 2 

Inquiry 


on 


Ry 



param 3 

returns 


<— 


Tx 

#$00 


param 4 

correct 


#$00 off 


Ty 

off 


param 5 

mode 




Vx 



param 6 





Vy 



Not valid if in joystick 

or fire button monitoring mode. 
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Data packet function 

When preceding a data packet returned from the keyboard, the special 
keycodes #$F6 to #$FF give the following meanings to the data packets: 


. Code 
Dec Hex 

Data packet function 

246 

F6 

Status report 

247 

F7 

Absolute mouse position record 

248 

F8 

\ Relative mouse position record 


to 

1 lllllOxx (xx=left-right button state) 


FB 

1 delta x, 2's complement 
/ delta y, 2's complement 

252 

FC 

Time of day (resolution of 1 second) 

253 

FD 

Joystick report header (both sticks) 

254 

FE 

xOOOyyyy \ x=trigger Joystick 0 event 

255 

FF 

xOOOyyyy / y=stick position Joystick 1 event 


6.7 






The Concise Atari ST Reference Guide 


6.8 



The Line-A routines 


Chapter 7 


The Line-A routines 

General 7.2 

Line-A access 7.2 

Initialization pointers 7.2 

The Line-A routines 7.3 

Put pixel 7.3 

Get pixel 7.3 

Line 7.3 

Horizontal line 7.3 

Filled rectangle 7.4 

Line-by-line filled polygon 7.4 

Bitblt 7.5 

Textblt 7.5 

Show mouse 7.5 

Hide mouse 7.5 

Transform mouse 7.6 

Undraw sprite 7.6 

Draw sprite 7.6 

Copy raster 7.6 

Contour fill 7.6 

Logic table 7.6 

Line-A parameter blocks 7.7 

Sprite definition block 7.7 

Format flag 7.7 

Memory definition block 7.7 

Line-A parameter table 7.8 

Bitblt table 7.10 
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The Line-A routines 

Atari ST programmers have access to the VDI primitives via the line-A 
exception routines; they provide a faster performance than the VDI routines, 
additional facilities and use less code to implement. The line-A routines may be 
mixed with VDI calls or used entirely on their own, but program portability to 
other systems will not be possible. 

Line-A access 

The line-A routines operate from a set of variables contained in a data table 
(Page 7.8 - 7.9). The table is initialized by activating the line-A exception vector in 
passing the word #$A000. The programmer may then alter or insert variables into 
the data table and call the required function by passing the appropriate function 
call word. 


dc.w 

#$A000 

; initialize data table 

move.w 

#n,d(A0) 

; set function at offset d 



; to value n 

dc.w 

#$A00m 

; call function 


Initialization pointers 

Initialization creates the following pointers: 

dO=base address of line-A variables 
aO=base address of line-A variables 
al=array of pointers to the 3 system font headers 
a2=array of pointers to the 15 line-A routines 

(a2 is not returned correctly on disk based versions of TOS) 


If VDI and AES are not used, the variables should be fairly static. If they are 
used, the variables may be changed, registers d0-d2 and a0-a2 will be trashed. 
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Line-A routines 


Pointpair Integers 

Function Op in out in out Comments 

$0 $2 $4 $6 $8 


Put 

pixel 

#$A001 10 10 

ptsin (0)=X_msbyte, Y_lsbyte 
intin (0)=pixel value 

Plot a pixel at x,y 

Get 

pixel 

#$A002 1 0 0 0 

ptsin (0)=X_msbyte, Y_lsbyte 

Get the pixel at x,y 
Return d0=pixel value 


Function 

Parameters 

Comments 

Line 

#$A003 

offset $26 XI coordinate 

Draw a line between 
X1,Y1 and X2,Y2 


$28 Y1 coordinate The line is ALWAYS drawn 

$2A X2 coordinate from left to right and the 

$2C Y2 coordinate mask applied left to right 

$18 plane 0 \ also- so watch the phase. 

$1A plane 1 I Bit 

$1C plane 2 I value / Mask is word aligned 

$lEplane3 / I pattern for horizontal 

$22 line style mask < I lines, i.e. any bit of 

$24 writing mode I mask may be used at the 

$20 -1 for XOR mode \ left-most endpoint, 

else ignore 

output Mask is rotated to align 

$22 line style mask with rightmost endpoint. 

Horizontal #$A004 Draw a line between 

Line offset $26 XI coordinate X1,Y1 and X2,Y1 

$28 Y1 coordinate The line is ALWAYS drawn 

$2A X2 coordinate from left to right 

$18 plane 0 \ 

$1A plane 1 I Bit 

$1C plane 2 I value 

$1E plane 3 / 

$24 writing mode 
$2E Fill pattern pointer 
$32 Fill pattern mask 
$34 Multi-plane fill flag 
output none 
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Line-A routines cont. 


Function Parameters 


Comments 


Filled #$A005 
rectangle offset 


output 


Draw a filled rectangle 

$26 XI coordinate with upper lefthand corner 

$28 Y1 coordinate X1,Y1 and lower righthand 

$2A X2 coordinate corner X2,Y2. 

$2C Y2 coordinate 
$18 plane 0 \ 

$1A plane 1 I Bit 

$1C plane 2 I value 

$1E plane 3 / 

$24 writing mode 

$2E Fill pattern pointer 

$32 Fill pattern mask 

$34 Multi-plane fill flag 

$36 Clipping flag 

$38 minimum X clipping value 

$3A maximum X clipping value 

$3C minimum Y clipping value 

$3E maximum Y dipping value 

none 


Line-by 

-line 

filled 

polygon 


#$A006 n 

ptsin (0)=X,Y array of 


offset 


output 


polygon vertices 


Draw one scan-line of a 
filled polygon. 


$28 Y1 coordinate 
$18 plane 0 \ 

$1A plane 1 I Bit 

$1C plane 2 I value 

$lEplane3 / 

$24 writing mode 
$2E Fill pattern pointer 
$32 Fill pattern mask 
$34 Multi-plane fill flag 
$36 Clipping flag 
$38 minimum X clipping value 
$3A maximum X clipping value 
$3C minimum Y clipping value 
$3E maximum Y clipping value 


Polygon 

Xl,Yl...Xn,Yn...Xl,Yl 
Start point must be 
repeated at the end 
of the list. 


Y1 is the Y coordinate 
of the line to fill. 


none 


XI and X2 trashed on return 
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Line-A routines cont. 


Function Parameters Comments 

Bitbit "#$A007 Bit block transfer 

input a6=i / p parameter table pointer See page 7.10 

output none for table entries 

Textblt #$A008 Perform a Text block 

offset $24=writing mode transfer of one character. 

$6A=Foreground \ Text 

$72=Background / colour 

$54=Pointer \ Writing mode 

$58=Width I Font 0-3 VDI modes 

$48=X coor I form 4-19 Bitblt modes 

$4A=Y coor / 

$4C=X coor \ Character 

$4E=Y coor / on screen 

$50=width \ Character 

$52=height / 

$5A=Style flag 
$5C=Lighten text mask 
$5E=Skew text mask 
$60=Thickening text width 
$62=above \ Character offset 
$64=below / from baseline 
$66=Scaling flag (0=none) 

$40=Accumulator for x dda 
$42=Textblt scale factor 
$44=Scale direction (down 0) 

$68=Character rotation vector 
$46=Font status 

$6C=Special effects buffer pointer 
$70=Scaling buffer offset in above pointer 



output 

none 


Show 

#$A009 


Show the mouse, if # of 

mouse 

input 

none 

'show' calls >= # of 


output 

none 

'hide' calls. 

Hide 

#$A00A 


Hide the mouse, if # of 

mouse 

input 

none 

'hide' calls exceeds # 


output 

none 

of 'show' calls. 
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Line-A routines cont. 

Function 

Parameters 

i Comments 

Trans 

#$A00B 

Transform mouse form 

-form 


cntrl $E=Addr.L source MFDB 

mouse 


cntrl $12=Addr.L destination MFDB 


output 

none 


Undraw #$A00C Undraw previously drawn 

sprite input a2=sprite slave block pointer sprite 

The sprite save block saves the 
screen underneath the sprite and is 
(lObytes + 648 # planes) bytes in size, 
output none *** a6 smashed *** 


Draw 

sprite 


#$A00D 

input 


output 


Draw a sprite 

dO=X hot spot (Function not available 

dl=Y hot spot on disk based versions 

aO=pointer to sprite definition block of TOS) 

a2=pointer to sprite save block 
none *** a6 smashed *** 


Copy #$A00E Copy a raster from source 

raster cntrl $E=Addr.L source MFDB to destination, 

form cntrl $12=Addr.L destination MFDB 

output none 

Contour "#$A00F Contour fill 

fill intin (0)=colour index input may be +ve or -ve. 

output none 


Logic table 


f g b g 


10 

$0A 

Op 0 

0 0 

11 

$0B 

Op 1 

0 1 

12 

$0C 

Op 2 

1 0 

13 

$0D 

Op_3 

1 1 

The 

logic 

operation bytes 

specify the effect of the foreground and 


background colour bits on the current plane. 
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Line-A parameter blocks 


Sprite definition block 


0 

$00 

2 

$02 

4 

$04 

6 

$06 

8 

$08 

10 

$0A 

12 

$0C 

74 

$4A 

76 

$4C 


X offset of hot-spot 
Y offset of hot-spot 
Format flag 
Background 
Foreground 
Interleaved 
background/ 

foreground 
image (32 words) 


\ Colour 
/ table index 

\ Background line 0 
I Foreground line 0 

/ Foreground line 16 


Format flag 

+ve -ve colour 

Fg Bg Fg Bg plotted 


0 0 0 0 
0 10 1 
1111 
1 0 

1 0 


Transparent 
Background 
Foreground 
Foreground 
XOR screen 


Memory form definition block (MFDB) 


0 

$00 

Memory pointer to 32-bit address of pixel 0,0 

4 

$04 

Width \ Raster 

area 

8 

$08 

Height / dimensions 

12 

$0C 

Word width 

Pixel width/word size 

16 

$10 

Format flag 

l=standard, 0=device specific 

20 

$14 

Memory planes 

# planes in raster area 

24 

$18 

\ Three 


28 

$1C 

1 reserved 


32 

$20 

/ words 


36 

$24 
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Line-A parameter table 


offset Function 

$00 0 Number of video planes \ Can produce special 

$02 2 Number of bytes/ video line / effects. 

$04 4 Pointer to cntrl array 

$08 8 Pointer to intin array 

$0C 12 Pointer to ptsin array 

$10 16 Pointer to intout array 

$14 20 Pointer to ptsout array 

$18 24 Bit plane_0 \ current 

$1A 26 Bit plane_l I colour 

$1C 28 Bit planeJ2 I value 

$1E 30 Bit plane_3 / 

$20 32 -1 

$22 34 VDI line style equivalent 

$24 36 Writing mode 0_replace l_transparent 

2_XOR mode 3 ^inverse transparent 

$26 38 XI coordinate 

$28 40 Y1 coordinate 

$2A 42 X2 coordinate 

$2C 44 Y2 coordinate 

$2E 46 Pointer to current fill pattern 

$32 50 Fill pattern mask (length of pattern) 

$34 52 Multi-plane fill pattern 

0_current fill pattern is single plane 
l_current fill pattern is multi-plane 
$36 54 Clipping flag 0_no clipping 
$38 56 Minimum x clipping value 

$3A 58 Minimum y clipping value 

$3C 60 Maximum x clipping value 

$3E 62 Maximum y clipping value 

$40 64 Accumulator for textblt x dda 

initialize to 8000H before each call 
$42 66 Textblt scale factor 

$44 68 Scale direction 0_down 
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Line-A parameter table cont. 


offset Function 
$46 70 Font status 

l_solid 

0_proportional or variable 
$48 72 X coordinate of character in font form 

$4A 74 Y coordinate of character in font form (typically 0) 

$4C 76 X coordinate of character on screen 

$4E 78 Y coordinate of character on screen 

$50 80 Character width 

$52 82 Character height 

$54 84 Pointer to start of font data (font form) 

$58 88 Width of font form 

$5A 90 Style bit 0_Thicken, bit l_lighten, bit 2_skew 
bit 3_underline (ignored), bit 4_outline 

$5C 92 Lighten text mask 

$5E 94 Skew text mask 

$60 96 Text thickening additional width 

$62 98 Offset above character baseline for skew 
$64 100 Offset below character baseline for skew 
$66 102 Scaling flag 0_no scaling 

$68 104 Character rotation vector 0_horizontal 900_vertically down etc. 

$6 A 106 Text foreground colour 
$6C 108 Special effects buffer pointer 
$70 112 Scaling buffer offset in above buffer 
$72 114 Text background colour (RAM VDI only) 

$74 116 Copy raster form type flag (RAM VDI only) 

0_opaque type 

n-plane source to n-plane destination bitblt write mode 
<>0_transparent type 

1-plane source to n-plane destination VDI write mode 
$76 118 Abort fill routine pointer (Function not available on disk based 

versions of TOS) 
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BITBLT table used in block transfers (routine $A008) 

Parameter block length must be 76 bytes, the first 52 bytes being set by the 
user and the remainder by the bit. Address register a6 is used as a pointer to the 
table, a point C programmers should note. 


* 

* 


* 


* 


0 

2 

4 

6 

8 

10 

11 

12 

13 

14 
16 
18 
22 
24 
26 
28 
30 
32 
36 
38 
40 
42 


46 

48 

50 


$00 

b_width 

$02 

b_height 

$04 

#planes 

$06 

fg_col 

$08 

bg_col 

$0A 

op_table 

$0B 


$0C 


$0D 


$0E 

s_xmin 

$10 

s_ymin 

$12 

s_rorm 

$16 

s_nxwd 

$18 

s_nxln 

$1A 

s_nxpl 

$1C 

d_xmin 

$1E 

d_ymin 

$20 

d_form 

$24 

d_nxwd 

$26 

d_nxln 

$28 

d_nxpl 

$2A 

p_addr 


$2D p_nxln 
$30 p_nxpl 
$32 p_mask 


width \ of block in 

height / pixels 

# of cosecutive planes to bit 

foreground colour - high bit \ logic operation 
background colour - low bit / index 
logic operation— Table of 4 raster operation code 
bytes, each containing one of sixteen 
logical operations. They are indexed 
by fg*2 + bg for each plane (see pg7.6). 
minimum source x 
minimum source y 

source form base address (word boundary) 

# word in line \ next offset (2hi-4med-81ow rez) 

# lines in plane / in bytes (90hi-160med/low rez) 
next plane offset from current (always 2) 
minimum destination x 

minimum destination y 

destination form base address (word boundary) 

# word in line \ next offset (2hi-4med-81ow rez) 

# lines in plane / in bytes (90hi-160med/low rez) 
next plane offset from current (always 2) 
address of pattern buffer (0=no pattern) 

A word size repetative, word aligned pattern 
that is ANDed with the source before being 
logically combined with the destination, 
next line in pattern \ offset (2, 4, 6 etc) 
next plane in pattern / in bytes (0=1 plane) 
pattern index mask length 


* may be altered during bitblt execution 


The source bit defined by s_xmin, s_ymin, b_width, b_height is transfered to 
destination d_xmin, d_ymin by the number of planes iterations (#planes). There 
is no clipping or check that bit blocks are within the encompassing memory 
forms. 
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Chapter 8 


The Blitter 


General 8.2 

Blitter operation 8.2 

Clipping 8.2 

Skew 8.2 

Endmasks 8.2 

Overlap 8.2 

Blitter control/status 8.3 

HOG bit 8.3 

BUSY bit 8.3 

Blitter access 8.3 

Blitter flow diagram 8.4 

Blitter parameter table 8.6 
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The Blitter 

General 

The New TOS versions of the Atari ST contain a hardware bit block transfer 
processor (blitter) which operates automatically on certain line-A and VDI 
functions, providing a considerable increase in the speed at which blocks of 
memory can be manipulated. The blitter can be switched off, or tested for 
presence, through the XBIOS $40 blitmode function. An attempt to 'turn on' the 
blit mode in a system which does not contain a blitter is ignored by the OS. The 
blitter should not be used from within an interrupt context where multiple blitter 
operations may conflict and cause unpredictable results. 

The blitter device moves bit aligned data in memory using one of sixteen 
logic operations. It can be used to provide rapid implementation of the following 
functions: 

Area seed fill 

Rotation and magnification 
Brush line drawing 

Text transformations eg. Bold, italic, outline 
Text scrolling 
Window updating 
Pattern filling 

Memory to memory block copying 

Blitter operation 

The blitter operates as follows,: Initially the transfer parameters are 

calculated before the data is moved, the parameters involved are: 

Clipping, sets the source and destination blocks to a predefined clipping 
rectangle size, the transfer is omitted if the block size is set to zero. Although the 
blocks are the same 'size', they may have different increments. 

Skew, the source to destination horizontal bit offset. 

Endmasks, provide start, intermediate and finish word masks to define the 
portion of the word in each line to be operated on. 

Overlap, a check that source data will not be overwritten before the transfer 
is complete, overlap reverses the default left to right transfer mode if necessary. 

The transfer is effected after the parameters have been calculated: 
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Blitter Control/Status 

Two bits in the blitter configuration registers are used to provide the 
programmer with control and the status of the blitter. 

The HOG bit when clear gives equal processor/blitter bus access (64 bus 
cycle segments), when set the processor is stopped until the blitter transfer is 
complete although other DMA processes can always interrupt the blitter. 

The BUSY bit is set after the other registers are initialised and is only cleared 
when the transfer is complete. Bus arbitration can still be used to initiate 
processor instructions, which means that the next instruction after the transfer is 
not necessarily that which set the BUSY bit. 

The blitter is usually operated with the HOG flag cleared. In this mode the 
blitter and the ST's CPU share the bus equally, each taking 64 bus cycles while the 
other is halted. This mode allows interrupts. 

Blitter access 

Use of the blitter generally entails access to hardware registers and so blitter 
routines are normally executed in supervisor mode. The following short 
assembly language routine ensures that the blitter is switched on and saves the 
original system state on the stack for later recovery. Note that if a blitter is not 
present, then this code will have no affect other than to waste a small amount of 
processor time. 


move.w 

#— 1,— (sp) 

move.w 

#$40,-(sp) 

trap 

#14 

adaq 

#4,sp 

move.w 

dO,-(sp) 

or.w 

#l,dO 

move.w 

dO,-(sp) 

move.w 

#$40,-(sp) 

trap 

#14 

adaq 

#4,sp 


; push get blitter status flag 
; push get/set blitter function call 
; call function 
; tidy stack 

; push blitter status for later use 
; set blitter on bit, do not touch other bits 
; push blitter on word 
; push function call 
; call function 
; tidy stack 


Do something, remembering that the stack contains the original system state 
which must not be destroyed if we wish to return to that state via something like: 


move.w #$40,-(sp) ; push function call 

trap #14 ; call function 

adaq #4,sp ; tidy stack 
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Blitter flow diagram 


Source 


X incr 
|(FF8A20V 


Y incr 
|(FF8A22)| 


Y incr 


SOURCE BUFFER 
Primarily used where 
the blocks are not 
aligned and two 
words need to be 
read. 


One word 
at a time 



The FXSR bit primes the source 
buffer with a dummy read so 
that the data may be ’skewed’ 
within the buffer and a valid 
word passed. 



The X incr and Y incr are 
15-bit 2’s complement 
values (in bytes) of the 
offset to the next word 
or line respectively. 

The SOURCE ADDRESS is 
a 23-bit word containing 
the address of the next 
word to be used. Updated 
by sign-extended X incr 
or Y incr as appropriate 
immediately after the 
source word fetch. 

Left to right, +ve incr’s 

Right to left, -ve incr's 

(SET BY OVERLAP TO PROTECT SOURCE, 
BUFFER TRANSFERS REVERSED HI-LO). 

The SKEW is the bit shift in 
the buffer of the source 
ce before being combined with 

yv * .destination data and 

stination halftone masks. 



The NFSR bit cancels the 
last read when the skew and 
endmask invalidate the last 
word in the line, although 
the buffer transfer still occurs 


(FXSR and NFSR require Y incr and the Source Address registers to be amended) 


Smudge 
register 
FF8A3C 
bit 5 


SMUDGE uses the least 
significant nibble of the 
skewed data as the 
halftone offset address 



LINE NUMBER defines which 
word is to be used for the 
current halftone line. 
Increasing or decreasing 
following the sign of the 
destination Y incr register, 
number wraps through zero. 

HALFTONE is a set of 
sixteen word patterns in RAM 
that may be used with the 
source or simply on its own 
as a mask. The mask is 
repeated every 16 lines. 
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Blitter flow diagram cont. 


Source 


write masks 


Endmask 1 

000 Ill 

FF8A28 


Original 

destination 


HOP 
register 
FF8A3A 
bits 0-1 




(s) 




(d) 

Logic OP 
register 




FF8A3B 
bits 0-3 


Flalftone 

HOP defines the source/halftone 
combination to be used as source 
in the logical operation. 

0 All Vs 

1 halftone 

2 source 

3 source AND halftone 


Logic Operations 

0 All O’s 8 NOT s AND NOT d 

1 s AND d 9 NOTsXORd 

2 SAND NOT d A NOT d 

3 s B s OR NOT d 

4 NOT s AND d C NOT s 

5 d D NOTsORd 

6 s XOR d E NOT s OR NOT d 

7 sORd F All 1’s 

Line first write and single word line 
mask only 


Endmask 2 

010 101 

FF8A2A 


Endmask 3 

111 000 - 

FF8A2C 


NEW 

DESTINATION 


Line 

intermediate 

word 


Line 

last 

write 


Only the bits 
corresponding to 
a T in the 
endmask will be 
updated. 


X incr 


Y incr 


M count 
lines) 


X count (words) and 
Y count (lines) define the 
size of the block and are 
counted down, reading 
the number still to be 
written. 

X count wraps on zero 
to its original value. 

A Y count of zero shows 
transfer complete. 

X incr and Y incr are 
15-bit 2's complement 
values (bytes) of the 
offset to the next word 
or line respectively. 

The destination address is a 23-bit word containing the address of the next word to 
be used. It is automatically updated by sign-extending X incr or Y incr as appropriate 
(Y incr if X count is one) immediately after the destination write. 




~n 







X count 

(words) 
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Blitter parameter table 


The blitter configuration registers are located at address $FF8A00 


Blitter offsets 

0 

$00 

halftone 

32 

$20 

src_xinc 

34 

$22 

src_yinc 

36 

$24 

src_addr 

40 

$26 

endmaskl 

42 

$28 

endmask2 

44 

$2A 

endmask3 

46 

$2C 

dst_xinc 

48 

$30 

dst_yinc 

50 

$32 

dst_addr 

54 

$36 

x_count 

56 

$38 

y count 

58 

$3A 

HOP 

59 

$3B 

OP 


60 $3C line_num 


61 $3D skew 


16 x 16 word pattern masks 

15-bit 2's complement increment of next word in source 
15-bit 2's complement increment of next line in source 
23-bit address of next word to be used in source 
destination write mask for first and single word lines 
destination mask for intermediate words on a line 
destination mask for the last word on a line 
15-bit 2's complement incr of next word in destination 
15-bit 2's complement incr of next line in destination 
23-bit address of next word to be used in destination 
number of words in line yet to be written, wraps on zero, 
number of lines yet to be written 


Halftone operation options 



0 

All l's 



1 

halftone 



2 

source 



3 

source AND halftone 



Logic operations 



0 

All 0's 

8 

NOT s AND NOT d 

1 

s AND d 

9 

NOT s XOR d 

2 

s AND NOT d 

A 

NOT d 

3 

s 

B 

s OR NOT d 

4 

NOT s AND d 

C 

NOTs 

5 

d 

D 

NOT s OR d 

6 

sXORd 

E 

NOT s OR NOT d 

7 

sORd 

F 

All l's 


Halftone mask line number 

bit 0-3 line number (0 to 15) - halftone index 

bit 5 Smudge - skew data nibble used as halftone index 

bit 6 HOG - l_halt processor while transfer. 0_share bus 

bit 7 BUSY - l_when registers initialised. Ojransfer over 

Source buffer bit shift 

bit 0-3 bit shift (0 to 15) - source skew 

bit 6 NFSR - l_no final source read. 0_normal 

bit 7 FXSR - l_force initial extra source read. 0_normal 
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The following tables present the system variables in low supervisor space $0 
to $7FF (0 to 2047): 


Exception vectors 


0 

$000 

Reset initial SSP value (ROM) 

4 

$004 

Reset initial PC address (ROM) 

8 

$008 

Bus error 

\ Dump state 

12 

$00C 

Address error 

1 and terminate 

16 

$010 

Illegal instruction / routine pointer 

20 

$014 

Divide by zero 

(Pointer to an RTE) 

24 

$018 

Chk instruction 

\ Dump state 

28 

$01C 

Trapv instruction 1 and terminate 

32 

$020 

Privilege violation 1 routine pointer 

36 

$024 

Trace mode 

/ 

40 

$028 

Line 1010 

line-A routine pointer 

44 

$02C 

Line 1111 

Used by AES 

48 

$030 

Unassigned 


52 

$034 

Coprocessor protocol violation (MC68020) 

56 

$038 

Format error (MC68020) 

60 

$03C 

Uninitialized interrupt vector 

64 

$040 

Unassigned 

\ 




1 Reserved 

82 

$05C 

Unassigned 

/ 

96 

$060 

Spurious interrupt (Hacked to level 3) 

100 

$064 

Int level 1 

(Used if user wants Hblanks) 

104 

$068 

Int level 2 

Horizontal blank sync (Hblank) 

108 

$06C 

Int level 3 

Normal processor interrupt level 

112 

$070 

Int level 4 

Vertical blank sync (Vblank) 

116 

$074 

Int level 5 


120 

$078 

Int level 6 

MK68901 MFP interrupts 

124 

$07C 

Int level 7 

Non maskable interrupt 

128 

$080 

Trap #0 


132 

$084 

Trap #1 

GEMDOS interface calls 

136 

$088 

Trap #2 

Extended DOS calls (AES, VDJ) 

140 

$08C 

Trap #3 


176 

$0B0 

Trap #12 


180 

$0B4 

Trap #13 

GEM BIOS calls 

184 

$0B8 

Trap #14 

Atari extended BIOS calls (XBIOS) 

188 

$0BC 

Trap #15 


192 

$0C0 

Unassigned 

\ 




1 Reserved 

252 

$0FC 

Unassigned 

/ 
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MFP hardware bound interrupt vectors 


* 

256 

$100 

* 

260 

$104 

* 

264 

$108 

* 

268 

$10C 

* 

272 

$110 


276 

$114 


280 

$118 

* 

284 

$11C 

* 

288 

$120 


292 

$124 


296 

$128 


300 

$12C 


304 

$130 

* 

308 

$134 

* 

312 

$138 

* 

316 

$13C 


320 

$140 


508 

$1FF 


Parallel port interrupt_0 (Centronics busy) 


RS232 carrier detect (dcd) 

RS232 clear to send (cts) 

Graphics bit done 
RS232 baud rate generator 
200Hz system clock 
Keyboard/MIDI (6850) 

Polled fdc/_hdc 
Horizontal blank counter 
RS232 transmit error interrupt 
RS232 transmit buffer empty interrupt 
RS232 receive error interrupt 
RS232 receive buffer full interrupt 
User/ application (Timer A) 

RS232 ring indicator interrupt 

Polled monochrome monitor detect interrupt 


interrupt_l 
interrupt_2 
interrupt_3 
(Timer D) 

(Timer C) 

interrupt_4 
interrupt_5 
(Timer B) 


Priority levels (7 high) 


* Initially disabled 

The polled fdc/_hdc interrupt must be disabled on return. 

Application interrupts 


512 $200 \ 

I Reserved for OEMs 
892 $37C / 

After an uncaught trap, the processor state is dumped as follows: 

Processor state 


896 

$380 

proc_lives 

900 

$384 

proc_regs 

964 

$3C4 

proc_pc 

968 

$3C8 

proc_usp 

972 

$3CC 

proc_stk 


Processor state saved if system 
variable set to $12345678 
D0-D7/A0-A6, A7_ssp 
First byte exception number 
USP 

sixteen words of superstack 


The above values are not overwritten by a system reset, but are by a further 
crash. 
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Address 

Size 

1024 $400 

L 

1028 $404 

L 

1032 $408 

L 

1036 $40C 

5xL 

1056 $420 

L 

1060 $424 

B 

1062 $426 

L 

1066 $42 A 

L 

1070 $42E 

L 

1074 $432 

L 

1078 $436 

L 

1082 $43 A 

L 

1086 $43E 

W 

1088 $440 

W 

1090 $442 

W 

1092 $444 

W 

1094 $446 

W 

1096 $448 

W 

1098 $44 A 

B 

1100 $44C 

B 

1102 $44 E 

L 

1106 $452 

W 

1108 $454 

W 

1110 $456 

L 

1114 $45A 

L 

1118 $45E 

L 

1122 $462 

L 

1126 $466 

L 


System variables 


etv_timer 

etv_critic 

etv_term 

etv_xtra 

memvalid 

memcntlr 

resvalid 

resvector 

phystop 

_membot 

_memtop 

memval2 

flock 

seekrate 

_timr_ms 

_fverify 

_bootdev 

palmode 

defshftmd 

sshiftmd 

_v_bas_ad 

vblsem 

nvbls 

_vblqueue 

colorptr 


screenpt 

_vbclock 

_frclock 


Function 

Timer handoff (logical vector $100) 

Critical error handoff vector ($101) 

Process terminate handoff vector ($102) 

Space for reserved logical 

vectors ($103-$107) 
#$752019F3 (cold start o'k) 
memory controller low nibble 
0=128K, 4=512K, (0=256K, 5=1MB 2 banks) 
#$31415926 to jump through resvector 
System reset bailout vector 

Physical RAMtop (points to first unusable byte 
Available memory bottom (getmpb uses) 
Available memory top (getmpb uses) 
#$237698AA for legal memory configuration. 

Floppy FIFO lock variable 
0=6ms, l=12ms, 2=2ms, 3=3ms default 
20 (#$14) system timer calibration 
0=no write-verify else verify (default) 

System boot device number 

0=NTSC, 60Hz else PAL, 50Hz 

Default video resolution if monitor changed 

Shadow shiftmd hardware register 

0=320x200x4 1=640x200x2 2=640x400x1 
Screen memory base pointer (32K contiguous) 
on a 512 byte boundary 
Vert blank mutual exclusion semaphore 
l_vblank enabled 

8 (No. longwords vblqueue points to) 

Vblank handler pointer to pointers 
0 null else pointer to 16 word vector 
for hardware palette next vblank 

Pntr to screen base next vblank or 0 
Vertical blank interrupt count 
Count vblank interrupts not vblsem'd 
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System variables cont. 


Address 

Size 


Function 

1130 $46 A 

L 

hdv_init 

Hard disk initialize vector else zero 

1134 $46E 

L 

swv_vec 

'Monitor changed' vector to follow 

1138 $472 

L 

hdv_bpb 

Hard disk vector to return bpb else 0 

1142 $476 

L 

hdv_rw 

Hard disk rd/wr routine vector else 0 

1146 $47A 

L 

hdv boot 

Hard disk boot routine vector else 0 

1150 $47E 

L 

hdv_mediach Disk media change routine vector else 0 

1154 $482 

W 

_cmdload 

<>0 load & exe COMMAND.PRG (boot device) 

1156 $484 

B 

conterm 

Attribute bits for console system, bit: 

0_bell on ( A G) l_keyrepeat 
2_keyclick 3_bios conin() function 

kbshft in bits 24 to 31 of DO.L 

1157 $485 

B 


reserved 

1158 $486 

L 

trpl4ret 

Saved trap 14 return address 

1162 $48 A 

L 

criticret 

Saved return address for etv_critic 

1166 $48E 

L 

themd 

GEMDOS memory descriptors (don't change) 
Structure MD 

m_link Next MD/ null 

m_start Start of TPA 

m_length Byte size of TPA 
m_own MD's owner/null 

1182 $49E 

W 

_md 

? reserved 

1186 $4A2 

L 

savptr 

_nflops 

BIOS register save area pointer 

1190 $4A6 

W 

# floppies attached 0, 1 or 2 

1192 $4A8 

L 

con_state 

State of conoutO parser (VT52 emulation) 

1196 $4AC 

W 

save_row 

Save row# for x-y addressing 

1198 $4AE 

L 

sav_contxt 

Pointer to saved processor context 

1202 $4B2 

L 

_bufl 

GEMDOS two buffer-list pointers 
1st buffers data sectors 


2nd buffers FAT and DIR sectors 


Structure BCB 


bjink 

Next BCB 

b_bufdrv 

Drive#/-1 

b_buftyp 

Buffer type 

b_bufrec 

Record# cached 

b_dirty 

Dirty flag 

b_dm 

Drive media descriptor 

b_bufr 

Buffer pointer 
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System variables cont. 

Address Size Function 

1210 $4BA L _hz_200 Raw 200Hz timer tick 

1214 $4BE L the_env Default environment string $00000000 

1218 $4C2 L _drvbits 32 bit vector of live block devices 

1222 $4C6 L _dskbufp Pointer to common disk buffer, 

1 Kbyte in systems BSS. 

(Do not use by an interrupt routine) 
1226 $4CA L autopath Pointer to autoexec path (or null) 

1230 $4CE 8xL vbljfist Initial vblqueue 

1262 $4EE W 

1264 $4F0 W 

1266 $4F2 L 

1270 $4F6 L 

1274 $4FA L 

1278 $4FE L 


2048 $800 


Bomb error codes 

meaning 
Bus error 

Address error (odd address) 
Illegal instruction 
Division by zero 
CHK exception 
TRAPV exception 
Privilege violation 
Trace exception 
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# bombs 

2 

3 

4 

5 

6 

7 

8 
9 


_prt_cnt Initially set -1, ALT_HELP increments 
screen-dump flag (0 abort) 
prtabt Printer abort flag 
_sysbase Base of OS pointer (RAM or ROM) 

_shell_p Global shell information pointer 
end_os Pointer to end of OS memory usage 
exec_os Pointer to shell address to execute on startup 
(normally 1st byte of AES text seg). 

Start of user RAM 
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Configuration registers 


Memory configuration registers B.2 

Display configuration registers B.2 

Reserved configuration register space B.3 

DMA/Disk configuration registers B.3 

Sound configuration registers B.4 

Blitter configuration registers B.5 

MK68901 configuration registers B.6 

MC6850 configuration registers B.6 
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Configuration Registers (one/_zero) 

MEMORY 

16744452 FF8004 r/w l....xxxxl Memory configurations 

Bank 0 Bank 1 (not used) 

0 128Kbyte 128Kbyte 

1 128Kbyte 512Kbyte 

2 128Kbyte 2Mbyte 

3 reserved 

4 512Kbyte 128Kbyte 

5 512Kbyte 512Kbyte 

6 512Kbyte 2Mbyte 

7 reserved 

8 2Mbyte 128Kbyte 

9 2Mbyte 512Kbyte 

10 2Mbyte 2Mbyte 

11 reserved 

12+ reserved 


DISPLAY 


16745061 

FF8201 

r/w 

1 xxxxxxxx 1 

Video base high 

16745063 

FF8203 

r/w 

1 xxxxxxxx 1 

Video base low 

16745065 

FF8205 

r 

1 xxxxxxxx 1 

Video address counter high 

16745067 

FF8207 

r 

1 xxxxxxxx 1 

Video address counter mid 

16745069 

FF8209 

r 

1 xxxxxxxx 1 

Video address counter low 

16745071 

FF820A 

r/w 

1 XX 1 

Sync mode 




bito 

External/ Internal sync 




bit 1 

50Hz/ 60Hz field rate 

16745124 

FF8240 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 0/0 (border) 




bitO 

Invert/ normal mono 




bit 0-2 

Blue 




bit 4-6 

Green 




bit 8-10 

Red 

16745126 

FF8242 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 1/1 

16745128 

FF8244 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 2/2 

16745130 

FF8246 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 3/3 

16745132 

FF8248 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 4 

16745134 

FF824A 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 5 

16745136 

FF824C 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 6 

16745138 

FF824E 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 7 

16745140 

FF8250 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 8 
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Configuration Registers (one/_zero) cont. 


16745142 

FF8252 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 9 

16745144 

FF8254 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 10 

16745146 

FF8256 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 11 

16745148 

FF8258 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 12 

16745150 

FF825A 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 13 

16745152 

FF825C 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 14 

16745154 

FF825E 

r/w 

1 xxx.xxx.xxx 1 

Palette colour 15 

16745156 FF8260 

Reserved 

r/w 

1 XX 1 

Shift mode 

0 320x200, 4 plane 

1 640x200, 2 plane 

2 640x400, 1 plane 

3 Reserved 

16745572 FF8400 

DMA/Disk 


1 1 

reserved 

16746084 

FF8600 


1 1 

reserved 

16746086 

FF8602 


1 1 

reserved 

16746088 

FF8604 

r/w 

1 xxxxxxxx 1 

Disk controller data access 

16746090 

FF8606 

r 

1 XXX 1 

bito 
bit 1 
bit 2 

DMA status (mode control) 
_Error 

_Sector count zero 
Data request inactive 


FF8606 

w 

1 xxxxxxxx. 1 

bit 1 
bit 2 
bit 3 
bit 4 
bit 5 
bit 6 
bit 7 
bit 8 

DMA mode control 
A0 ) WD1772 
A1 ) registers 
HDC/_FDC register select 
Sector count register select 
0 reserved 

Disable/ enable DMA 

FDC/_HDC 

Write/_read 

16746093 

FF8609 

r/w 

1 xxxxxxxx 1 

DMA base and counter high 

16746095 

FF860B 

r/w 

1 xxxxxxxx 1 

DMA base and counter mid 

16746097 

FF860D 

r/w 

1 xxxxxxxx 1 

DMA base and counter low 
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SOUND 

16746596 


16746598 


Configuration Registers (one/_zero) cont. 


FF8800 


FF8802 


r I xxxxxxxx I 


PSG read data 
I/O port B, Parallel i/f data 


w I xxxxxxxx I 

reg# 
8 bit 0 
4 bit 1 
8 bit 2 
4 bit 3 
8 bit 4 

4 bit 5 

5 bit 6 
8 bit 7 
5 bit 8 
5 bit 9 
5 bit 10 
8 bit 11 
8 bit 12 
4 bit 13 

14 

15 


PSG register select 

Channel A fine tune 
Channel A coarse tune 
Channel B fine tune 
Channel B coarse tune 
Channel C fine tune 
Channel C coarse tune 
Noise generator control 
Mixer control-I/O enable 
Channel A amplitude 
Channel B amplitude 
Channel C amplitude 
Envelope period fine tune 
Envel period coarse tune 
Envelope shape 
I/O port A (output only) 
I/O port B (Centronics O/P) 


w I xxxxxxxx I 

bitO 
bit 1 
bit 2 
bit 3 
bit 4 
bit 5 
bit 6 
bit 7 


PSG write data, I/O port A 
Floppy side 0/_side 1 select 
Floppy _drive 0 select 
Floppy _drive 1 select 
RS232 RTS 
RS232 DTR 
Centronics STROBE 
General purpose output 
Reserved 


r/w I xxxxxxxx I 


I/O port B, Par i/f data 
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Configuration Registers (one/_zero) cont. 


Blitter 


16747108 

FF8A00 

1 xxxxxxxxxxxxxxxx 1 

Halftone RAM 

16747110 

FF8A02 

I xxxxxxxxxxxxxxxx 1 


16747112 

FF8A04 

1 xxxxxxxxxxxxxxxx 1 

16x16 pattern 
mask 

16747138 

FF8A1E 

1 xxxxxxxxxxxxxxxx 1 

16747140 

FF8A20 

1 xxxxxxxxxxxxxxx. 1 

Source increment X 

16747142 

FF8A22 

1 xxxxxxxxxxxxxxx. 1 

Source increment Y 

16747144 

FF8A24 

1 xxxxxxxx 1 

\ Source address 

16747146 

FF8A26 

1 xxxxxxxxxxxxxxx. 1 

/ 

16747148 

FF8A28 

1 xxxxxxxxxxxxxxxx 1 

Endmask 1 

16747150 

FF8A2A 

1 xxxxxxxxxxxxxxxx 1 

Endmask 2 

16747152 

FF8A2C 

1 xxxxxxxxxxxxxxxx 1 

Endmask 3 

16747154 

FF8A2E 

1 xxxxxxxxxxxxxxx. 1 

Destination increment X 

16747156 

FF8A30 

1 xxxxxxxxxxxxxxx. 1 

Destination increment Y 

16747158 

FF8A32 

1 xxxxxxxx 1 

\ Destination address 

16747160 

FF8A34 

1 xxxxxxxxxxxxxxx. 1 

/ 

16747162 

FF8A36 

1 xxxxxxxxxxxxxxxx 1 

count x (words across) 

16747164 

FF8A38 

1 xxxxxxxxxxxxxxxx 1 

count y (lines down) 

16747166 

FF8A3A 

1 XX 1 

HOP halftone operation 

16747167 

FF8A3B 

1 xxxx 1 

OP logic operation 

16747168 

FF8A3C 

1 xxx.xxxx 1 

bit 0-3 

bit 5 
bit 6 
bit 7 

Halftone mask line 
line number of halftone 
pattern RAM 
Smudge 
HOG 
Busy 

16747169 

FF8A3D 

1 XX. ..xxxx 1 

bit 0-3 
bit 6 
bit 7 

Source buffer skew 
source skew shift 
NFSR toggle 
FXSR toggle 


B.5 




The Concise Atari ST Reference Guide 


Configuration Registers (one/_zero) cont. 


MK68901 


16775681 

FFFA01 

1 xxxxxxxx 1 

bitO 
bit 4 
bit 5 
bit 7 

MFP general purpose I/O 
Parallel port status 
WD1772 active 
Interrupt 
Mono monitor 

16775683 

FFFA03 

1 xxxxxxxx 1 

MFP active edge 

16775685 

FFFA05 

1 xxxxxxxx 1 

MFP data direction 

16775687 

FFFA07 

1 xxxxxxxx 1 

MFP interrupt enable A 

16775689 

FFFA09 

1 xxxxxxxx 1 

MFP interrupt enable B 

16775691 

FFFA0B 

1 xxxxxxxx 1 

MFP interrupt pending A 

16775693 

FFFA0D 

1 xxxxxxxx 1 

MFP interrupt pending B 

16775695 

FFFA0F 

1 xxxxxxxx 1 

MFP intrpt in-service A 

16775697 

FFFA11 

1 xxxxxxxx 1 

MFP intrpt in-service B 

16775699 

FFFA13 

1 xxxxxxxx 1 

MFP interrupt mask A 
MFP interrupt mask B 

16775701 

FFFA15 

1 xxxxxxxx 1 

16775703 

FFFA17 

1 xxxxxxxx 1 

MFP vector base 

16775705 

FFFA19 

1 xxxxxxxx 1 

MFP timer A control 

16775707 

FFFA1B 

1 xxxxxxxx 1 

MFP timer B control 

16775709 

FFFA1D 

1 xxxxxxxx 1 

MFP timers C & D control 

16775711 

FFFA1F 

1 xxxxxxxx 1 

MFP timer A data 

16775713 

FFFA21 

1 xxxxxxxx 1 

MFP timer B data 

16775715 

FFFA23 

1 xxxxxxxx 1 

MFP timer C data 

16775717 

FFFA25 

1 xxxxxxxx 1 

MFP timer D data 

16775719 

FFFA27 

1 xxxxxxxx 1 

MFP sync character 

16775721 

FFFA29 

1 xxxxxxxx 1 

MFP USART control register 

16775723 

FFFA2B 

1 xxxxxxxx 1 

MFP receiver status 

16775725 

FFFA2D 

1 xxxxxxxx 1 

MFP transmitter status 

16775727 

FFFA2F 

1 xxxxxxxx 1 

MFP USART data 

MC6850 

16776192 

FFFC00 

1 xxxxxxxx 1 

Keyboard ACIA control 

16776194 

FFFC02 

1 xxxxxxxx 1 

Keyboard data 

16776196 

FFFC04 

1 xxxxxxxx 1 

Midi ACIA control 

16776198 

FFFC06 

1 xxxxxxxx i 

Midi data 


All unused bits read zero. 
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Printer and terminal escape codes 


Typical Epson printer codes C.2 

VT52 terminal escape codes C.4 

Printers C.5 
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Typical Epson Printer Codes 


Code 
Dec Hex 

Ascii Function 

Mnemo 

Dec 

***** 

Hex 

ESC code functions ***** 
Ch 

0 

00 

NUL 


32 

20 



1 

01 

SOH 


33 

21 

I 

Combine print modes 

2 

02 

STX 

* for one 

34 

22 

" 


3 

03 

ETX 

line only 

35 

23 

# 


4 

04 

EOT 


36 

24 

$ 


5 

05 

ENQ 


37 

25 

% 

Select ROM/ user charset 

6 

06 

ACK 


38 

26 

& 

Define user characters 

7 

07 

BEL 

Bell 

39 

27 

/ 


8 

08 

BS 

Backspace 

40 

28 

( 


9 

09 

HT 

Tab horizontal 

41 

29 

) 


10 

0A 

LF 

Line feed 

42 

2A 

* 

Select graphics mode 

11 

0B 

VT 

Tab vertical 

43 

2B 

+ 


12 

OC 

FF 

Form feed 

44 

2C 



13 

0D 

CR 

Carriage Return 

45 

2D 

- 

Underline on/off 

14 

0E 

SO 

* Enlarged on 

46 

2E 



15 

OF 

SI 

Condensed on 

47 

2F 

/ 

Select vert Tab channel 

16 

10 

DLE 


48 

30 

0 

Set 1/8 inch LF 

17 

11 

DC1 

On-line printer 

49 

31 

1 

Set 7/72 inch LF 

18 

12 

DC2 

Condensed off 

50 

32 

2 

Set 1/6 inch LF 

19 

13 

DC3 

Off-line printer 

51 

33 

3 

Set n/216 inch LF 

20 

14 

DC4 

* Enlarged off 

52 

34 

4 

Italic on 

21 

15 

NAK 


53 

35 

5 

Italic off 

22 

16 

SYN 


54 

36 

6 


23 

17 

ETB 


55 

37 

7 


24 

18 

CAN Clear print buffer 

56 

38 

8 

Detect paper-out on 

25 

19 

EM 

Cut sheet feeder 

57 

39 

9 

Detect paper-out off 

26 

1A 

SUB 


58 

3A 


Copy ROM char to RAM 

27 

IB 

ESC 


59 

3B 



28 

1C 

FS 


60 

3C 

< 

* Unidirection print 

29 

ID 

GS 


61 

3D 

= 


30 

IE 

RS 


62 

3E 

> 


31 

IF 

US 


63 

3F 

? 

Redefine graphic mode 





- 64 

40 

@ 

Initialize printer 

32 

20 



65 

41 

A 

Set n/72 inch LF 



Printable ASCII codes 

66 

42 

B 

Set vertical Tabs 

127 

7F 



67 

43 

C 

n Set form length 





- 68 

44 

D 

Set horizontal Tabs 





69 

45 

E 

Bold on 





70 

46 

F 

Bold off 
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Typical Epson Printer Codes cont. 

***** ESC code functions ***** ***** ESC code functions ***** 


Dec 

Hex 

Ch 


Dec 

Hex 

Ch 


71 

47 

G 

Double strike on 

110 

6E 

n 


72 

48 

H 

Double strike off 

111 

6F 

o 


73 

49 

I 


112 

70 

p 

Proportional on /off 

74 

4A 

J 

LF n/216 inch 

113 

71 

q 


75 

4B 

K 

60 dpi bitimage 

114 

72 

r 


76 

4C 

L 

120 dpi bitimage 

115 

73 

s 

Half speed on/off 

77 

4D 

M 

Elite on 

116 

74 

t 


78 

4E 

N 

Skip perforation on 

117 

75 

u 


79 

4F 

O 

Skip perforation off 

118 

76 

V 


80 

50 

P 

Pica on /Elite off 

119 

77 

w 


81 

51 

Q 

Set right column 

120 

78 

X 

Select draft/NLQ mode 

82 

52 

R 

Select character set 

121 

79 

y 


83 

53 

S 

Super/ subscript on 

122 

7 A 

iz 


84 

54 

T 

Super/subscript off 

123 

7B 

{ 


85 

55 

U 

Unidirection on/ off 

124 

7C 

1 


86 

56 

V 


125 

7D 

} 


87 

57 

W 

Enlarged on/off 

126 

7E 



88 

58 

X 


127 

7F 

del 

Cancel last character 

89 

59 

Y 

120 dpi bitimage-fast 





90 

5A 

Z 

240 dpi bitimage 





91 

5B 

[ 






92 

5C 

\ 






93 

5D 

] 






94 

5E 

A 

Set 9 pin bit image 





95 

5F 







96 

60 

/ 






97 

61 

a 

Set NLQ justify 





98 

62 

b 

Set vertical tabs channels 




99 

63 

c 






100 

64 

d 






101 

65 

e 

Set hor/ver Tab increment 




102 

66 

f 

Paperfeed/Tab execute 




103 

67 

g 






104 

68 

h 






105 

69 

i 






106 

6A 

j 






107 

6B 

k 






108 

6C 

1 

Set left margin 





109 

6D 

m 

Special character generator 
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VT52 terminal escape codes 

The following BIOS bconoutO functions simulate a VT52 terminal, with 
extensions for colour, screen wrap etc. 

Esc Function Comments 


A Cursor up Up one line, no affect if at top 

B Cursor down Down one line, no affect if at bottom 

C Cursor right Right one position, no affect if at edge 

D Cursor left Left one position, no affect if at edge 

E Clear screen Clear screen and home cursor to column 0, row 0 
H Home cursor Home cursor to column 0, row 0 

I Cursor up Up one line, if at top scroll 

J Erase to eop Erase to end of page from and including cursor position 

K Clear to eol Clear to end of line from cursor position 

L Insert line Insert blank line with cursor at start of line. 

Move current line down 

M Delete line Delete cursor line and move remaining lines up one, 

put blank at bottom. 

Y,r,c Cursor r,c Position cursor at row r column c 

b, f fgd colour f Colour is the 4 lsb of colour byte 

c, b bgd colour b Colour is the 4 lsb of colour byte 

d Erase to start Erase to start of page including the current cursor position 
of page 

e Show cursor Show cursor 

f Hide cursor Hide cursor 

j Save cursor Save the cursor position 

k Restore cursor Restore cursor, home if no saved posn 

1 Erase line Erase line and move cursor left edge 

o Erase to start Erase to start of line from and including the cursor 

of line 

p Reverse video Enter reverse video mode 

q Normal video Exit reverse video mode 

v Wrap at end Wrap at end of line and scroll up if necessary 
of line 

w Discard end Overprint line end character with the next character 
of line 
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Escape Codes 


Printers 

In general an Atari printer that is designed to work with the ST will provide 
the most suitable path to trouble free computer/printer interfacing and the 
production of hard copy printout and screen dumps. Where a printer from 
another manufacturer is to be used, the following may be of use: 


If screen dumps are required, the code IB 4C (27 76 dec) should be 
recognized as 'double density bit image mode' for printing 960 dots/line at 120 
dots/inch on 8" wide paper (the dump is virtually the same size as the monitor 
screen display) or code IB 59 (27 89 dec) for the wider paper screen dumps. 


It may reasonably be assumed that whatever word processor you employ, it 
will provide the necessary print configuration file to make available the printers 
facilities. Double clicking a non-executable file icon to print it's contents should 
not cause problems as control codes are not sent within the text. The ST does 
however precede the file with the code to select draft or NLQ (near letter quality) 
print, i.e ESC,"x",n. 


Some serial printers are restricted to 2400 and 600 baud operation, the ST 
supports neither rate without recource to C or assembly language programming. 


C.5 




The Concise Atari ST Reference Guide 


C.6 



Keycode Definitions 


Appendix D 


Keycode definitions 


Ascii codes 

D.3 

GSX compatible keyscan codes 
VDI standard keyboard codes 

D.4 

D.5 

Note that the keycodes returned do differ for the 

different international 

keyboards. 
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ASCII codes 0 to 127 


Dec 

Ascii 

Dec 

Ascii 

Dec 

Ascii 

Dec 

Ascii 

0 

NUL 

32 

SPACE 

64 

@ 

96 

/ 

1 

SOH 

33 

1 

65 

A 

97 

a 

2 

STX 

34 

ii 

66 

B 

98 

b 

3 

ETX 

35 

# 

67 

C 

99 

c 

4 

EOT 

36 

$ 

68 

D 

100 

d 

5 

ENQ 

37 

% 

69 

E 

101 

e 

6 

ACK 

38 

& 

70 

F 

102 

f 

7 

BEL 

39 

' 

71 

G 

103 

g 

8 

BS 

40 

( 

72 

H 

104 

h 

9 

HT 

41 

) 

73 

I 

105 

i 

10 

LF 

42 

* 

74 

J 

106 

j 

11 

VT 

43 

+ 

75 

K 

107 

k 

12 

FF 

44 


76 

L 

108 

1 

13 

CR 

45 

- 

77 

M 

109 

m 

14 

SO 

46 


78 

N 

110 

n 

15 

SI 

47 

/ 

79 

O 

111 

0 

16 

DLE 

48 

0 

80 

P 

112 

p 

17 

DC1 

49 

1 

81 

Q 

113 

q 

18 

DC2 

50 

2 

82 

R 

114 

r 

19 

DC3 

51 

3 

83 

S 

115 

s 

20 

DC4 

52 

4 

84 

T 

116 

t 

21 

NAK 

53 

5 

85 

U 

117 

u 

22 

SYN 

54 

6 

86 

V 

118 

V 

23 

ETB 

55 

7 

87 

W 

119 

w 

24 

CAN 

56 

8 

88 

X 

120 

X 

25 

EM 

57 

9 

89 

Y 

121 

y 

26 

SUB 

58 


90 

Z 

122 

Z 

27 

ESC 

59 


91 

[ 

123 

{ 

28 

FS 

60 

< 

92 

\ 

124 

i 

29 

GS 

61 

= 

93 

] 

125 

} 

30 

RS 

62 

> 

94 

A 

126 

~ 

31 

US 

63 

7 

95 

- 

127 

DEL 


D.2 





Keycode Definitions 


GSX compatible keyscan codes 


. Code 
Dec Hex 

Keytop 

. Code 
Dec Hex 

Keytop 

. Code 
Dec Hex 

Keytop 

1 

01 

ESC 

38 

26 

L 

75 

4B 

left arrow 

2 

02 

1 

39 

27 

/ 

76 

4C 

n.u 

3 

03 

2 

40 

28 

' 

77 

4D 

right arrow 

4 

04 

3 

41 

29 

' 

78 

4E 

kpd + 

5 

05 

4 

42 

2A 

left shift 

79 

4F 

n.u 

6 

06 

5 

43 

2B 

\ 

80 

50 

down arrow 

7 

07 

6 

44 

2C 

Z 

81 

51 

n.u 

8 

08 

7 

45 

2D 

X 

82 

52 

INSERT 

9 

09 

8 

46 

2E 

C 

83 

53 

DEL 

10 

0A 

9 

47 

2F 

V 

84 

54 

n.u to 

11 

0B 

0 

48 

30 

B 

95 

5F 

n.u 

12 

OC 

- 

49 

31 

N 

96 

60 

ISO key 

13 

0D 

CR 

50 

32 

M 

97 

61 

UNDO 

14 

0E 

BS 

51 

33 

/ 

98 

62 

HELP 

15 

OF 

TAB 

52 

34 


99 

63 

kpd ( 

16 

10 

Q 

53 

35 

/ 

100 

64 

kpd ) 

17 

11 

W 

54 

36 

right shift 

101 

65 

kpd / 

18 

12 

E 

55 

37 

n.u 

102 

66 

kpd * 

19 

13 

R 

56 

38 

ALT 

103 

67 

kpd 7 

20 

14 

T 

57 

39 

space bar 

104 

68 

kpd 8 

21 

15 

Y 

58 

3A 

caps lock 

105 

69 

kpd 9 

22 

16 

U 

59 

3B 

FI 

106 

6A 

kpd 4 

23 

17 

I 

60 

3C 

F2 

107 

6B 

kpd 5 

24 

18 

o 

61 

3D 

F3 

108 

6C 

kpd 6 

25 

19 

p 

62 

3E 

F4 

109 

6D 

kpd 1 

26 

1A 

[ 

63 

3F 

F5 

110 

6E 

kpd 2 

27 

IB 

] 

64 

40 

F6 

111 

6F 

kpd 3 

28 

1C 

RET 

65 

41 

F7 

112 

70 

kpd 0 

29 

ID 

CNTL 

66 

42 

F8 

113 

71 

kpd . 

30 

IE 

A 

67 

43 

F9 

114 

72 

kpd ENTER 

31 

IF 

S 

68 

44 

F10 

115 

73 

n.u 

32 

20 

D 

69 

45 

n.u 

116 

74 

left_m/jstk_0 

33 

21 

F 

70 

46 

n.u 

117 

75 

rt_m/jstk_l 

34 

35 

22 

23 

G 

H 

71 

72 

47 

48 

HOME 
up arrow 

UK Keyboard 

36 

24 

j 

73 

49 

nu 

43 

2B 

# 

37 

25 

k 

74 

4A 

kpd - 

96 

60 

\ 


Returned highword lowbyte from the BDOS c_conin function 
n.u = not used xx_m/jstk_l=mouse/joystick button 
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GEM VDI standard keyboard codes 


High Low Character 
byte bvte 

High Low Character 
bvte byte 

High Low Character 
bvte bvte 

03 

00 

Ctl 2 

39 

20 

space 

1 

03 

40 

@ 

IE 

01 

Ctl A 

02 

21 

IE 

41 

A 

30 

02 

Ctl B 

28 

22 

" 

30 

42 

B 

2E 

03 

Ctl C 

2B/04 23 

# 

2E 

43 

C 

20 

04 

Ctl D 

05 

24 

$ 

20 

44 

D 

12 

05 

Ctl E 

06 

25 

% 

12 

45 

E 

21 

06 

Ctl F 

08 

26 

& 

21 

46 

F 

22 

07 

Ctl G 

28 

27 

t 

22 

47 

G 

23 

08 

Ctl H 

OA 

28 

( 

23 

48 

H 

17 

09 

Ctl I 

OB 

29 

) 

17 

49 

I 

24 

0A 

CtlJ 

09 

2A 

* 

24 

4A 

J 

25 

0B 

Ctl K 

OD 

2B 

+ 

25 

4B 

K 

26 

OC 

Ctl L 

33 

2C 


26 

4C 

L 

32 

OD 

Ctl M 

OC 

2D 


32 

4D 

M 

31 

OE 

Ctl N 

34 

2E 


31 

4E 

N 

18 

OF 

Ctl O 

35 

2F 

/ 

18 

4F 

O 

19 

10 

Ctl P 

OB 

30 

0 

19 

50 

P 

10 

11 

Ctl Q 

02 

31 

1 

10 

51 

Q 

13 

12 

Ctl R 

03 

32 

2 

13 

52 

R 

IF 

13 

Ctl S 

04 

33 

3 

IF 

53 

S 

14 

14 

Ctl T 

05 

34 

4 

14 

54 

T 

16 

15 

Ctl U 

06 

35 

5 

16 

55 

U 

2F 

16 

Ctl V 

07 

36 

6 

2F 

56 

V 

11 

17 

Ctl W 

08 

37 

7 

11 

57 

W 

2D 

18 

Ctl X 

09 

38 

8 

2D 

58 

X 

15 

19 

Ctl Y 

OA 

39 

9 

15 

59 

Y 

2C 

1A 

Ctl Z 

27 

3A 


2C 

5A 

Z 

1A 

IB 

Ctl [ 

27 

3B 


1A 

5B 

[ 

2B 

1C 

Ctl \ 

33 

3C 

< 

2B 

5C 

\ 

IB 

ID 

Ctl ] 

OD 

3D 

= 

IB 

5D 

] 

07 

IE 

Ctl 6 

34 

3E 

> 

07 

5E 

A 

OC 

IF 

Ctl - 

35 

3F 

? 

OC 

5F 

underscore 
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GEM VDI standard keyboard codes cont. 


High Low Character 
byte byte 


High Low Character 
byte byte 


60 

' 

81 

00 

Alt 0 

11 

00 

61 

a 

78 

00 

Alt 1 

2D 

00 

62 

b 

79 

00 

Alt 2 

15 

00 

63 

c 

7A 

00 

Alt 3 

2C 

00 

64 

d 

7B 

00 

Alt 4 

3B 

00 

65 

e 

7C 

00 

Alt 5 

3C 

00 

66 

f 

7D 

00 

Alt 6 

3D 

00 

67 

g 

7E 

00 

Alt 7 

3E 

00 

68 

h 

7F 

00 

Alt 8 

3F 

00 

69 

i 

80 

00 

Alt 9 

40 

00 

6A 

j 

IE 

00 

Alt A 

41 

00 

6B 

k 

30 

00 

Alt B 

42 

00 

6C 

1 

2E 

00 

Alt C 

43 

00 

6D 

m 

20 

00 

Alt D 

44 

00 

6E 

n 

12 

00 

Alt E 

54 

00 

6F 

0 

21 

00 

Alt F 

55 

00 

70 

P 

22 

00 

Alt G 

56 

00 

71 

q 

23 

00 

Alt H 

57 

00 

72 

r 

17 

00 

Alt I 

58 

00 

73 

s 

24 

00 

AltJ 

59 

00 

74 

t 

25 

00 

Alt K 

5A 

00 

75 

u 

26 

00 

Alt L 

5B 

00 

76 

V 

32 

00 

Alt M 

5C 

00 

77 

w 

31 

00 

Alt N 

5D 

00 

78 

X 

18 

00 

Alt O 

5E 

00 

79 

y 

19 

00 

Alt P 

5F 

00 

7A 

z 

10 

00 

Alt Q 

60 

00 

7B 

( 

13 

00 

Alt R 

61 

00 

3 7C 

1 

IF 

00 

Alt S 

62 

00 

7D 

} 

14 

00 

Alt T 

63 

00 

7E 


16 


Alt U 

64 


7F 

DEL 

2F 


Alt V 

65 



Alt_W 

Alt_X 

Alt_Y 

Alt_Z 

FI 

F2 

F3 

F4 

F5 

F6 

F7 

F8 

F9 

F10 

Shf_Fl 

Shf_F2 

Shf_F3 

Shf_F4 

Shf_F5 

Shf_F6 

Shf_F7 

Shf_F8 

Shf_F9 

Shf_F10 

* F21 

* F22 

* F23 

* F24 

* F25 

* F26 


These scan codes are not supported by the Atari ST BIOS 
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GEM VDI standard keyboard codes cont. 


High Low 
bvte bvte 

Character 

High Low 
bvte byte 

Character 

66 

00 

* F29 

53 

2E 

Shift delete 

67 

00 

* F30 

72 

00 

* Ctl print screen 

68 

00 

* F31 

37 

2A 

* Print screen 

69 

00 

* F32 

01 

IB 

Escape 

6A 

00 

* F33 

0E 

08 

Backspace 

6B 

00 

* F34 

82 

00 

Alt - 

6C 

00 

* F35 

83 

00 

Alt = 

6D 

00 

* F36 

1C 

0D 

CR 

6E 

00 

* F37 

1C 

0A 

Ctl cr 

6F 

00 

* F38 

4C 

35 

Shift number pad 5 

70 

00 

* F39 

4A 

2B 

Number pad - 

71 

00 

* F40 

4E 

2B 

Number pad + 

73 

00 

Ctl left arrow 

OF 

09 

Tab 

4D 

00 

Right arrow 

OF 

00 

* Backtab 

4D 

36 

Shft right arrow 

4B 

00 

Left arrow 

74 

00 

Ctl right arrow 

4B 

34 

Shift left arrow 

50 

00 

Down arrow 

4F 

00 

* End 

50 

32 

Shift down arrow 

4F 

31 

* Shift end 

48 

00 

up arrow 

75 

00 

* Ctl end 

48 

38 

Shift up arrow 




51 

00 

* Page down 




51 

33 

* Shift page down 




76 

00 

* Ctl_ page down 




49 

00 

* Page up 




49 

39 

* Shift page up 




84 

00 

* Ctl_ page up 




77 

00 

Ctl home 




47 

00 

Home 




47 

37 

Shift home 




52 

00 

Insert 




52 

30 

Shift insert 




53 

00 

Delete 





* These scan codes are not supported by the Atari ST BIOS 
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Callable Functions 


Appendix E 


List of callable functions 


BIOS (Trap #13) 

E.2 

XBIOS (Trap #14) 

E.2 

GEMDOS (Trap #1) 

E.4 

Extended BDOS (Trap #2) 

E.5 

GEM VDI 

E.6 

GEM AES 

E.9 

ikbd command set 

E.12 

Line-A routines 

E.13 
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List of callable functions 


BIOS calls (Trap #13) 


. Code 
Dec Hex 


Function 

Pg.# 

0 

00 

getmpb 

Get and fill memory parameter block 

3.4 

1 

01 

bconstat 

Return character-device input status 

3.4 

2 

02 

bconin 

Input character to device, return when done 

3.4 

3 

03 

bconout 

Output character to device, return when done3.4 

4 

04 

rwabs 

Read /write logical sectors from /to device 

3.5 

5 

05 

setexc 

Get or set vector number 

3.5 

6 

06 

tickcal 

Return system timer value (ms) 

3.5 

7 

07 

getbpb 

Return pointer to BIOS parameter block 

3.5 

8 

08 

bcostat 

Return character output device status 

3.5 

9 

09 

mediach 

Check for media change 

3.5 

10 

0A 

drvmap 

Get/ set bit map and logical drives 

3.6 

11 

0B 

kbshft 

Set keyboard shift bits 

3.6 


Callable from user mode, re-entrant to three levels 


Device = 0_Printer, parallel port 
l_Aux, RS232 port 
2_Con, screen 
3_Midi 
4_Keyboard 


XBIOS calls (Trap #14) 


. Code 


Function 

Pg.# 

Dec 

Hex 



0 

00 

inimous 

Initialize mouse packet handler 

3.7 

1 

01 

ssbrk 

Reserve X bytes from top memory 

3.7 

2 

3 

02 

03 

_physbase 

_logbase 

Get screens physical base address 
Get screens logical base 

3.7 

3.8 

4 

04 

_getRez 

Get screens current resolution 

3.8 

5 

05 

setScreen Set screen logical location 

3.8 

6 

06 

_setPalette Set hardware palette registers 

3.8 

7 

07 

setcolor 

Set the palette number 

3.8 

8 

08 

_floprd 

Read sectors from floppy disk 

3.8 

9 

09 

_flopwr 

Write sectors to floppy disk 

3.9 
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XBIOS calls (Trap #14) cont. 


. Code 


Function 

Pg.# 

Dec 

Hex 



10 

0A 

_flopfmt 

Format floppy disk 

3.9 

11 

OB 

getdsb 

Get device status block pointer 

3.9 

12 

OC 

midiws 

Write string to MIDI port 

3.9 

13 

0D 

_mfpint 

Set MFP interrupt number 

3.9 

14 

0E 

iorec 

Return pointer to serial device buffer record 

3.10 

15 

OF 

rsconf 

Configure RS232 port 

3.10 

16 

10 

keytbl 

Set/get pointer to keyboard translation table 

3.10 

17 

11 

_random 

Return 24 bit pseudo random number 

3.10 

18 

12 

_protobt 

Prototype image boot sector 

3.11 

19 

13 

_flopver 

Verify sectors from floppy 

3.11 

20 

21 

14 

15 

scrdmp 

cursconf 

Dump screen to printer 
Get/set cursor blink/attributes 

3.11 

3.11 

22 

16 

settime 

Set keyboard time and date 

3.11 

23 

17 

gettime 

Get time and date from keyboard 

3.11 

24 

18 

bioskeys 

Restore keyboard translation tables 

3.12 

25 

19 

ikbdws 

Write string to interrupt keyboard 

3.12 

26 

1A 

jdisint 

Disable interrupt # on MK68901 

3.12 

27 

IB 

jenabint 

Enable interrupt # on MK68901 

3.12 

28 

1C 

giaccess 

Read/write sound chip register 

3.12 

29 

ID 

offgibit 

Set port A bit to 0 atomically 

3.12 

30 

IE 

ongibit 

Set port A bit to 1 atomically 

3.12 

31 

IF 

xbtimer 

Set MFP timers and control registers 

3.12 

32 

20 

dosound 

Set pointer to sound command bytes 

3.13 

33 

21 

setprt 

Set/get printer configuration byte 

3.13 

34 

22 

kbdvbase 

Return pointer to keyboard structure 

3.13 

35 

23 

kbrate 

Get/ set keyboard repeat rate 

3.13 

36 

24 

_prtblk 

Hard copy routine 

3.14 

37 

25 

vsync 

Wait for next vblank 

3.14 

38 

26 

supexec 

Execute in super mode 

3.14 

39 

64 

27 

40 

puntaes 

blitmode 

Throw away AES 
Get/ set blitter status 

3.14 

3.14 


Callable from user mode. 


E.3 



The Concise Atari ST Reference Guide 


GEMDOS calls (Trap #1) 


. Code 
Dec Hex 


Function 

Pg.# 

0 

00 

p_term_o 

Terminate process (use $4c) 

3.15 

1 

01 

c_conin 

Read character from standard input 

3.15 

2 

02 

c conout 

Write character to standard output 

3.15 

3 

03 

c_auxin 

Read character from aux device 

3.15 

4 

04 

c auxout 

Write character to aux device 

3.15 

5 

05 

c_prnout 

Write character to standard print device 

3.15 

6 

06 

c rawio 

Raw input to standard input 

3.16 

7 

07 

c rawcin 

Raw input from standard input 

3.16 

8 

08 

c_necin 

Read character from standard input -no echo 3.16 

9 

09 

c conws 

Write null terminated string to standard o/p 

3.16 

10 

0A 

c_conrs 

Read editted string from standard input 

3.16 

11 

OB 

c conis 

Check status of standard input 

3.16 

14 

0E 

d setdrv 

Set default drive 

3.16 

16 

10 

c conos 

Check status of standard output 

3.16 

17 

11 

c_prnos 

Check status standard print device 

3.16 

18 

12 

c_auxis 

Check status standard aux device input 

3.16 

19 

13 

c auxos 

Check status standard aux device output 

3.17 

25 

19 

d getdrv 

Get current drive 

3.17 

26 

1A 

f setdta 

Set disk transfer address 

3.17 

42 

2A 

t getdate 

Get date 

3.17 

43 

2B 

t setdate 

Set date 

3.17 

44 

2C 

t_gettime 

Get time 

3.17 

45 

2D 

t settime 

Set time 

3.17 

47 

2F 

f_getdta 

Get disk transfer address 

3.17 

48 

30 

s version 

Get version number 

3.17 

49 

31 

p tenures 

Terminate and stay resident 

3.17 

54 

36 

d free 

Get drive free space 

3.18 

57 

39 

d create 

Create a subdirectory 

3.18 

58 

3A 

d_delete 

Delete a subdirectory 

3.18 

59 

3B 

d setpath 

Set current directory 

3.18 

60 

3C 

f create 

Create a file 

3.18 

61 

3D 

f open 

Open file 

3.18 

62 

3E 

f close 

Close file 

3.18 

63 

3F 

f read 

Read file 

3.19 

64 

40 

f write 

Write file 

3.19 

65 

41 

f delete 

Delete file 

3.19 

66 

42 

f seek 

Seek file pointer 

3.19 

67 

43 

f attrib 

Get/Set file attribute 

3.19 

69 

45 

f_dup 

Duplicate file handle 

3.19 
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Callable Functions 


GEMDOS calls (Trap #1) cont. 


. Code 
Dec Hex 


Function 

Pg.# 

70 

46 

f force 

Force file handle 

3.20 

71 

47 

d getpath 

Get current directory 

3.20 

72 

48 

m _alloc 

Allocate memory 

3.20 

73 

49 

m free 

Free allocated memory 

3.20 

74 

4A 

m shrink 

Shrink size of allocated memory 

3.20 

75 

4B 

p_exec 

Load or execute a process 

3.20 

76 

4C 

p term 

Terminate process 

3.21 

78 

4E 

f sfirst 

Search for first occurrence of filespec 

3.21 

79 

4F 

f_snext 

Search for next occurrence of filespec 

3.21 

86 

56 

f rename 

Rename a file 

3.21 

87 

57 

f_datime 

Get/set file date and time stamp 

3.22 

32 

20 

smode 

Set/get supervisor/ user mode 

3.23 


Extended BDOS call (Trap #2) 


. Code 
Dec Hex 

Function 

Pg.# 

0 00 System reset 

System /program control 

3.25 

115 73 

VDI access 

3.25 

200 c8 

AES access 

3.25 

201 c9 



-2 fe 

GDOS version test 

3.25 
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GEM VDI functions 


Op 

Definition 

Printer 

Metafile 


code 



Screen 


Plotter 


Pg.# 

*1 

Open workstation ) Use virtual 

X 

X 

X 

X 

'4*5 

*2 

Close workstation ) workstation 

X 

X 

X 

X 

4.9 

3 

Clear workstation 

X 

X 

X 

X 

4.9 

4 

Update workstation 

X 

X 

X 

X 

4.9 

5 

Escape code 







1 

Inquire address of character cells 

X 

X 

X 

X 

4.27 


2 

Exit alpha mode 

X 



X 

4.27 


3 

Enter alpha mode 

X 



X 

4.27 


4 

Cursor up 

X 




4.27 


5 

Cursor down 

X 




4.27 


6 

Cursor right 

X 




4.27 


7 

Cursor left 

X 




4.27 


8 

Home cursor 

X 




4.27 


9 

Erase to screen end 

X 




4.28 


10 

Erase to line end 

X 




4.28 


11 

Direct cursor address 

X 




4.28 


12 

Output cursor addressable text 

X 




4.28 


13 

Reverse video on 

X 




4.28 


14 

Reverse video off 

X 




4.28 


15 

Inquire current alpha cursor address 

X 




4.28 


16 

Inquire tablet status 



X 


4.29 


17 

Hard copy 


X 



4.29 


18 

Place graphic cursor 

X 




4.29 


19 

Remove last graphic cursor 

X 




4.29 


* 20 

Form advance 


X 


X 

4.30 


* 21 

Output window 


X 


X 

4.30 


* 22 

Clear display list 


X 


X 

4.30 


* 23 

Output bit image file 


X 


X 

4.30 


* 60 

Select palette 




X 

4.30 


*91 

Inquire palette film types 




*x 

4.31 


*92 

Inquire palette driver state 




X 

4.31 


* 93 

Set palette driver state 




X 

4.31 


*94 

Save palette driver state 




X 

4.31 


*95 

Suppress palette messages 




X 

4.31 


*96 

Palette error inquire 




X 

4.32 


*98 

Update metafile extents 




X 

4.32 


*99 

Write metafile item 




X 

4.32 


* 100 Change GEM VDI filename 




X 

4.32 


* Not implemented on the Atari ST 
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Callable Functions 


GEM VDI functions cont. 

Op Definition 
code 

Printer Metafile 

Screen Plotter Pg. # 

6 

Polyline 

X 

X 

X 

X 

4.10 

7 

Polymarker 

X 

X 

X 

X 


8 

Text 

X 

X 

X 

X 


9 

Filled area 

X 

X 

X 

X 


10 

Cell array 

X 

X 

X 

X 


11 

Escape code Generalized drawing primitives (GDP) 




1 Bar 

X 

X 

X 

X 

4.11 


2 Arc 

X 

X 

X 

X 



3 Pie 

X 

X 

X 

X 



4 Circle 

X 

X 

X 

X 



5 Ellipse 

X 

X 

X 

X 



6 Elliptical arc 

X 

X 

X 

X 



7 Elliptical pie 

X 

X 

X 

X 

4.12 


8 Rounded rectangle 

X 

X 

X 

X 



9 Filled rounded rectangle 

X 

X 

X 

X 



10 Justified graphics text 

X 

X 

X 

X 


12 

Set character height absolute mode 

X 

X 

X 

X 

4.14 

13 

Set character baseline vector 

X 



X 


14 

Set colour representation 

X 



X 

4.13 

15 

Set polyline linetype 

X 

X 

X 

X 


16 

Set polyline line width 

X 



X 


17 

Set polyline colour index 

X 

X 

X 

X 


18 

Set polymaker type 

X 

X 

X 

X 

4.14 

19 

Set polymarker height 

X 



X 


20 

Set polymarker colour index 

X 

X 

X 

X 


21 

Set text face 

X 

X 

X 

X 


22 

Set text colour index 

X 

X 

X 

X 


23 

Set fill interior style 

X 

X 

X 

X 

4.15 

24 

Set fill style index 

X 

X 

X 

X 

4.15 

25 

Set fill colour index 

X 

X 

X 

X 

4.15 

26 

Inquire colour representation 

X 

X 

X 


4.23 

27 

Inquire cell array 

X 



X 

4.25 

* 28 

Input locator 

X 



X 

4.20 

* 29 

Input valuator, request/ sample 

X 



X 

4.20 

* 30 

Input choice, request/sample 

X 



X 

4.21 

*31 

Input string 

X 



X 

4.21 

32 

Set writing mode 

X 

X 


X 

4.13 

*33 

Set input mode 

X 



X 

4.20 


* Not implemented on the Atari ST 












E.7 




The Concise Atari ST Reference Guide 


GEM VDI functions cont. 






Op 

Definition 

Printer 

Metafile 


code 


Screen 


Plotter 


Pg.# 

35 

Inquire current polyline attributes 

X 

X 

X 

X 

4.23 

36 

Inquire current polymarker attributes 
Inquire current fill area attributes 

X 

X 

X 

X 

4.23 

37 

X 

X 

X 

X 

4.23 

38 

Inquire current graphic text attributes 

X 

X 

X 

X 

4.24 

39 

Set graphic text alignment 

X 

X 

X 

X 

4.15 

100 

Open virtual screen workstation 

X 




4.9 

101 

Close virtual screen workstation 

X 




4.9 

102 

Extended inquire function 

X 

X 

X 

X 

4.22 

103 

Contour fill 




X 

4.10 

104 

Set fill perimeter visibility 

X 

X 

X 

X 

4.15 

105 

106 

Inquire pixel 

Set grapn text special effects 

X 

X 


X 

4.17 

4.15 

107 

Set character cell height, points mode 

X 

X 

X 

X 

4.14 

108 

Set polyline and styles 

X 

X 

X 

X 

4.13 

109 

Copy raster, opaque 

X 




4.17 

110 

Transform form 

X 




4.17 

111 

Set mouse form 

X 




4.18 

112 

Set user-defined fill pattern 

X 

X 


X 

4.15 

113 

Set user-defined linestyle 

X 



X 

4.13 

114 

Fill rectangle 

X 



X 

4.10 

115 

Inquire input mode 

X 




4.25 

116 

Inquire text extent 

X 

X 

X 


4.24 

117 

Inquire character cell width 

X 

X 

X 

X 

4.24 

118 

Exchange timer interrupt vector 

X 




4.18 

119 

Load fonts 

X 




4.9 

120 

Unload fonts 

X 




4.9 

121 

Copy raster, transparent 

X 




4.17 

122 

Show cursor 

X 




4.18 

123 

Hide cursor 

X 




4.18 

124 

Sample mouse button state 

X 


X 


4.18 

125 

Exchange button change vector 

X 




4.18 

126 

Exchange mouse movement vector 

X 




4.19 

127 

Exchange cursor change vector 

X 




4.19 

128 

Sample keyboard state information 

X 




4.19 

129 

Set dipping rectangle 

X 

X 


X 

4.9 

130 

Inquire facename and index 

X 

X 

X 


4.24 

131 

Inquire current face information 

X 

X 

X 

X 

4.25 


The standard range of VDI function output devices include a camera and a 
tablet as well as the screen, printer, plotter and metafile; Only the screen is 
implemented in the Atari ST. 
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Callable Functions 


GEM AES function calls 


Op# Description Pg # 


Application library routines 


10 

Initialise application 

APPL INIT 

5.6 

11 

Read message from pipe 

APPL READ 

5.6 

12 

Write message to pipe 

APPL WRITE 

5.6 

13 

14 

Find another application 
Playback GEM recording 

APPL FIND 
APPL TPLAY 

5.6 

5.7 

15 

Record GEM session 

APPL TRECORD 

5.7 

19 

Cleanup and exit 

APPL EXIT 

5.7 


Timer event routines 


20 

Waiting for keyboard input 

EVNT KEY 

5.8 

21 

Waiting for button input 

EVNT BUTTON 

5.8 

22 

Waiting for mouse input 

EVNT MOUSE 

5.8 

23 

Waiting for message input 

EVNT MESAG 

5.9 

24 

Waiting period 

EVNT TIMER 

5.9 

25 

Waiting for multi-events 

EVNT MULTI 

5.1( 

26 

Get/ set mouse clickrate 

EVNT DCLICK 

5.1( 


Menu library routines 


30 

Toggle applicatn menu bar 

MENU BAR 

5.12 

31 

Toggle menu check mark 

MENU ICHECK 

5.12 

32 

Toggle menu item able 

MENU IENABLE 

5.12 

33 

Toggle display video 

MENU TNORMAL 

5.12 

34 

Change item menu text 

MENU TEXT 

5.12 

35 

Put accessr/s menu in desk MENU_REGISTER 

5.12 

Object library routines 

40 

Add object to tree 

OBJC ADD 

5.18 

41 

Delete object from tree 

OBJC DELETE 

5.18 

42 

Draw an object or tree 

OBJC DRAW 

5.18 

43 

Find object under mouse 

OBJC FIND 

5.18 

44 

Compute object offset 

OBJC OFFSET 

5.18 

45 

Change object tree order 

OBJC ORDER 

5.19 

46 

Edit objects text 

OBJC EDIT 

5.19 

47 

Change objects state 

OBJC CHANGE 

5.19 
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GEM AES function calls cont. 


Op# Description Pg # 

Form library routines 


50 

Monitor user/form 

FORM DO 

5.20 

51 

Toggle dialog boxes 

FORM DIAL 

5.20 

52 

Display alert box 

FORM ALERT 

5.20 

53 

Display error box 

FORM ERROR 

5.20 

54 

Centre dialog box 

FORM CENTER 

5.20 

Graphics library routines 

70 

Draw a rubber box 

GRAF RUBBERBOX 

5.24 

71 

Drag a box around 

GRAF DRAGBOX 

5.24 

72 

Draw moving box 

GRAF MOVEBOX 

5.24 

73 

Draw expanding outline 

GRAF GROWBOX 

5.25 

74 

Draw shrinking outline 

GRAF SHRINKBOX 

5.25 

75 

Test for mouse inside 

GRAF WATCHBOX 

5.25 

76 

Slide box in parent 

GRAF SLIDEBOX 

5.25 

77 

Return screen handle 

GRAF HANDLE 

5.26 

78 

Redefine mouse form 

GRAF MOUSE 

5.26 

79 

Return mouse attributes 

GRAF MKSTATE 

5.26 

Scrap library routines 

80 

Read clipboard directory 

SCRP_READ 

5.27 

81 

Write directory to clipboard SCRP_WRITE 

5.27 

File selector routines 

90 

Display file selector box 

FSELJNPUT 

5.28 

Window library routines 

100 

Allocate full window 

WIND CREATE 

5.29 

101 

Open window to size 

WIND OPEN 

5.29 

102 

Close window 

WIND CLOSE 

5.29 

103 

Deallocate window 

WIND DELETE 

5.29 

104 

Get window data 

WIND GET 

5.30 

105 

Set window data 

WIND SET 


106 

Find mouse window 

WIND FIND 

5.32 

107 

Update window 

WIND UPDATE 

5.32 

108 

Calculate window data 

WIND CALC 

5.32 
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Callable Functions 


GEM AES function calls cont. 


Op# Description Pg # 


Resource library routines 

110 

Load resource file 

RSRC LOAD 

5.35 

111 

Deallocate resource file 

RSRC FREE 

5.35 

112 

Get structure address 

RSRC GADDR 

5.35 

113 

Save structure index 

RSRC SADDR 

5.35 

114 

Convert charaters to pixels 

RSRC OBFIX 

5.35 

Shell library routines 

120 

Find how created 

SHEL READ 

5.37 

121 

Exit AES or run other 

SHEL WRITE 

5.37 

122 

Get data 

SHEL GET 

5.37 

123 

Put data 

SHEL PUT 

5.37 

124 

Find filename path 

SHEL FIND 

5.37 

125 

Find parameter address 

SHEL ENVRN 

5.37 
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Intelligent keyboard (ikbd) command set 


Code 
Dec Hex 

Command Function 

Pg.# 

128 

80 

Reset Return keyboard to power-up status 

6.3 

1 

01 

without affecting the clock. 

A break of 200ms also causes a reset 


7 

07 

Set mouse button action 

6.3 

8 

08 

Set mouse relative position reporting 

6.3 

9 

09 

Set mouse absolute positioning 

6.3 

10 

0A 

Set mouse keycode mode 

6.3 

11 

0B 

Set mouse threshold 

6.3 

12 

OC 

Set mouse scale 

6.3 

13 

0D 

Interrogate mouse position 

6.3 

14 

0E 

Load mouse position 

6.4 

15 

OF 

Set Y = 0 at bottom 

6.4 

16 

10 

Set Y = 0 at top 

6.4 

17 

11 

Resume 

6.4 

18 

12 

Disable mouse 

6.4 

19 

13 

Pause output 

6.4 

20 

14 

Set joystick event reporting 

6.4 

21 

15 

Set joystick interrogation mode 

6.4 

22 

16 

Joystick interrogation 

6.4 

23 

17 

Set joystick monitoring 

6.4 

24 

18 

Set fire button monitoring 

6.4 

25 

19 

Set joystick keycode mode 

6.5 

26 

1A 

Disable joysticks 

6.5 

27 

IB 

Set time of day clock 

6.5 

28 

1C 

Interrogate time of day clock 

6.5 

32 

20 

Memory load 

6.5 

33 

21 

Memory read 

6.6 

34 

22 

Controller execute 

6.6 

OR 

80 

Status inquiries (OR 80H with command) 

6.6 


The status of the keyboard can be determined by interrogating the status 
register in the configuration tables. 
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Callable Functions 


Line-A routines 


Dec 

Hex 

Line-A function 

Pg.# 

20480 

A000 

Initialization 

7.3 

20481 

A001 

Put pixel 

7.3 

20482 

A002 

Get pixel 

7.3 

20483 

A003 

Line 

7.3 

20484 

A004 

Horizontal line 

7.3 

20485 

A005 

Filled rectangle 

7.4 

20486 

20487 

A006 

A007 

Line_by_line filled polygon 

BitBlt (including half tone source patterns) 

7.4 

7.5 

20488 

A008 

TextBlt (all 16 BitBlt logic operations) 

7.5 

20489 

A009 

Show mouse 

7.5 

20490 

A00A 

Hide mouse 

7.5 

20491 

AOOB 

Transform mouse 

7.6 

20492 

AOOC 

Undraw sprite 

7.6 

20493 

AOOD 

Draw sprite 

7.6 

20494 

AOOE 

Copy raster form 

7.6 

20495 

AOOF 

Contour fill 

7.6 
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Parameter Blocks 


Appendix F 


Parameter blocks 

System 

System start-up block F.2 

Boot sector parameter block F.2 

Device drivers 

Device driver F.3 

Device state block F.3 

Floppy parameter block F.4 

Sector buffer block F.4 

Program parameter blocks 

Transient program area block F.5 

Load parameter block F.5 

Base page format F.5 

File header F.6 

Memory parameter block F.6 

GEM parameter blocks 
VDI 

Parameter block F.7 

Cntrl table F.7 

AES 

Parameter block F.8 

Cntrl table F.8 

Global array block F.8 

Line-A variables 

Line-A tables F.9 

Undocumented line- A variables F.ll 

Sprite definition block F.12 

Memory form definition block F.12 

Header blocks 

Cartridge header block F.13 

Application header block F.13 

Run flag bits F.13 
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System 


System start-up block 


0 

$00 

Reseth 

2 

$02 

Vers 

4 

$04 

Reseth 

8 

$08 

Ostext 

12 

$0C 

Endos 

16 

$10 

Reseth 

20 

$14 

Magic 

24 

$18 

Date 


Branch to reset handler 
OS version number 
System reset handler 
Base of Operating system 
End of OS memory used 
Default shell 

Verification number or zero 
System build date 


\ 

I Pointers 
/ 


Boot sector parameter block 


0 

$00 

BRA.S 

Branch to boot code 

2 

$02 

OEM's space 

Reserved for OEMs use 

8 

$08 

Vol ser # 

24 bit volume serial number 

11 

$0B 

BPS 

Number of bytes/ sector 

13 

$0D 

SPCs 

Number of sectors/cluster 

14 

$0E 

RES 

Number of reserved sectors 

16 

$10 

NFATS 

Number of file alocation tables 

17 

$11 

NDIRS 

Number of directory entries 

19 

$13 

NSECTS 

Number of sectors on media 

21 

$15 

MEDIA 

Media descriptor - not used 

22 

$16 

SPF 

Number of sectors /FAT 

24 

$18 

SPT 

Number of sectors/track 

26 

$1A 

NSIDES 

Number of sides on media 

28 

$1C 

NHID 

Number of hidden sectors-not used 

30 

$1E 

boot code 

Start of code, if any ? 

511 

512 

$1FE last word 
$200 

Used for checksum 
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Parameter Blocks 


Device drivers 


Each device has one driver (Device control block-DCB) that contains entry 
points to routines and constants used by the systems to initialize the device's 
state during a warm-start. The routines and constants are defined as follows: 

Device driver 

0 $00 BREAD Read sector 

4 $04 B WRITE Write sector 

8 $08 BINIT Initialize drive (warm start) 

12 $0C BFORMAT Format drive 

16 $10 BINTR Vblank call (time-out homing) 

20 $14 BRDTRK Read track 

24 $18 BWRTRK Write track 

28 $1C BXLATE Logical to physical translate 

32 $20 BCVSIZ CSV size allocation 

34 $22 BALVSIZ ALV size allocation 

38 $26 BDEFINFO Default information block 

42 $2A 

Device drivers are stored in RAM in a device state block (DSB), the DSB 
contains TOS specific data structures (the DPB and DPH) and device specific 
information, such as the number of tracks, head seek rate. The DSB is allocated 
during a warm-start. 

Device state block 


0 

$00 

DDPH 

Device parameter header 

26 

$1A 

DDPB 

Disk parameter block 

42 

$2A 

DINFOSIZ 

DSB size (not incl DDPH) 

44 

$2C 

DPHYSDEV 

Device physical number 

46 

$2E 

DNTRACKS 

Number of tracks on device 

48 

$30 

DSPT 

Number of sectors/track 

50 

$32 

DNSIDES 

Number of sides/ device 

52 

$34 

DSEEKRT 

Floppy seek rate 

54 

$36 
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Floppy parameter block 


0 

$00 

Flock 

Floppy lock return address 

4 

$04 

Cret 

Callers return address 

8 

$08 

Dmayn 

DMA pointer 

12 

$0C 


Obsolete 

16 

$10 

Devno 

Device number 

18 

$12 

Secno 

Sector number 

20 

$14 

Trkno 

Track number 

22 

$16 

Sidno 

Side number 

24 

$18 

Secnt 

Sector count 

26 

$la 




Sector buffer block 


0 

$00 

BNEXT 

4 

$04 

BBUF 

8 

$08 

BLRU 

12 

$0C 

BFLAGS 

14 

$0E 

BDEV 

16 

$10 

BTRACK 

18 

$12 

BSIDE 

20 

$14 

BSSECT 

22 

$16 

BESECT 

24 

$18 

BPSECT 

26 

$1A 

BS1ZE 


Next buffer or null 
Size of buffer (512 bytes) 
LRU replacement value 
Valid/dirty flags 
Device number 
Track number 
Side number 
Start sector number 
End sector number 
Physical sector number 
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Program parameter blocks 


Transient program area block 


Low TPA 


Base pave 


To maintain maximum 

Text 


GEM DOS compatibility, 

Data 


free unused memory and 
lower top of stack (4A). 

BSS 


Determine memory 
available and allocate it. 

Application 

user area 

High TPA 



Load block 


0 

4 

$00 

$04 


Opened program file address 
Base address to load program 

8 

$08 


Program end address +1 

12 

$0C 


Address of Base Page 

16 

$10 


Default user stack pointer 

20 

$14 


Loader control flags 
0_load at bottom 
l_load at top 

22 

$16 


Base page format block 


0 

$00 

Low TPA 

Base address of TPA 

4 

$04 

Hi TPA 

End of TPA + 1 

8 

$08 

Tbase 

Base address of text 

12 

$0C 

Tien 

Length of text 

16 

$10 

Dbase 

Base address of initialized data 

20 

$14 

Dlen 

Length of data 

24 

$18 

Bbase 

Base address of BSS uninitialized data 

28 

$1C 

Blen 

Length of BSS uninitialized data 
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Atari OS specific base page 


32 

$20 

Length free memory after BSS 


36 

$24 

Drive from which program loaded 


37 

$25 

Reserved by BDOS 


56 

$38 

Second parsed FCB \ Command 

\ Set 

92 

$5C 

First parsed FCB / line 

1 by 

128 

$80 

Command tail and default 

/ OS 



DMA buffer 



$FF 

end 



GEMDOS specific base page 


32 

$20 

36 

$24 

40 

$28 

44 

$2C Environ 

128 

$80 Cmdline 

File 

header 

0 

$00 BRA.S flag 

2 

$02 

6 

$06 

10 

$0A 

14 

$0E 

18 

$12 

22 

$16 

26 

$1A 

File 

header extension 


DTA address pointer 
Parents Base Page pointer 
Reserved 

Environment string pointer 
Command line image 


/ 601AH data & BSS contiguous 

\ else 601BH 

Bytes in text segment 

Bytes in data segment 

Bytes in BSS 

Bytes in symbol table 

Zero (reserved) 

Start of text segment & program execution 
Zero if no relocation bits 


(If BSS and data not contiguous:- Not supported by Atari OS) 


28 $1C Start address of data segment 

32 $20 Start address of BSS 

36 $24 


Memory parameter block 


0 $00 


Owner description 
# bytes in block 
Start address of block 
Next link MD 
Roving pointer 
Memory allocation list 
Memory free list 


\ 

I Memory 
I descriptor 
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GEM parameter blocks 


VDI parameter block 


Longword addresses 


0 

$00 

contrl 

4 

$04 

intin 

8 

$08 

ptsin 

12 

$0C 

intout 

16 

$10 

ptsout 

20 

$14 


Control table pointer 
I/P attribute table pointer 
I/P points table pointer 
O/P attribute table pointer 
O/P points table pointer 


VDI control table 


0 $00 Op code 

2 $02 Ljptsin 

4 $04 Ljptsout 

6 $06 WJntin 

8 $08 WJntout 

10 $0A 

12 $0C 

14 $0E 


Function op code 

I/P coordinate \ Size in \ 

O/P coordinate / longwords I Table 

I/P attribute \ Size in I sizes 

O/P attribute / words / 


Subfunction identification number 
Device handle 

Op code dependent information 
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AES parameter block 


0 

$00 

cntrl 

4 

$04 

global 

8 

$08 

intjn 

12 

$0C 

int_out 

16 

$10 

addrjn 

20 

$14 

addrjmt 

24 

$18 



Longword addresses 

Control table pointer 
Global array pointer 
I/P attribute table pointer 
I/P points table pointer 
O/P attribute table pointer 
O/P points table pointer 


AES control table 


0 

$00 

Op code 

2 

$02 

WJntJn 

4 

$04 

W_int_out 

6 

$06 

L_addr_in 

8 

$08 

L_addr_out 

10 

$0A 



AES 

global array 

0 

$00 

version 

2 

$02 

count 

4 

$04 

id 

6 

$06 

private 

10 

$0A 

ptree 

14 

$0E 

reserved 

18 

$12 

reserved 

22 

$16 

reserved 

26 

$1A 

reserved 

30 

$1E 



Function op code 

I/P coordinate \ Size in \ 

O/P coordinate / words I Table 

I/P attribute \ Size in I sizes 

O/P attribute / longwords / 


GEM AES version identification word 
Maximum #concurrent applications allowed 
Unique application identifier 
Longword user data 
Resource address tree pointer 

I Zero 
I 

/ 
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Line-A variables 


Line-A parameter table 

Function 

0 $00 Number of video planes \ Can produce special 

2 $02 Number of bytes /video line / effects. 

4 $04 Pointer to Cntrl array 

8 $08 Pointer to Intin array 

12 $0C Pointer to Ptsin array 

16 $10 Pointer to In tout array 

20 $14 Pointer to Ptsout array 

24 $18 Bit plane_0 \ current 

26 $1A Bit plane_l I colour 

28 $1C Bit plane_2 I value 

30 $1E Bit plane_3 / 

32 $20 -1 

34 $22 VDI line style equivalent 

36 $24 Writing mode 0_replace 1 _transparent 

2_XOR mode 3_inverse transparent 

38 $26 XI coordinate 

40 $28 Y1 coordinate 

42 $2A X2 coordinate 

44 $2C Y2 coordinate 

46 $2E Pointer to current fill pattern 

50 $32 Fill pattern mask 

52 $34 Multi-plane fill pattern 

0_current fill pattern is single plane 
l_current fill pattern is multi-plane 
$36 54 Clipping flag 0_no clipping 

$38 56 Minimum x clipping value 

$3A 58 Minimum y clipping value 

$3C 60 Maximum x clipping value 

$3E 62 Maximum y clipping value 

$40 64 Accumulator for textblt x dda, initialize to 8000H before each call 

$42 66 Textblt scale factor 

$44 68 Scale direction 0_down 
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Line-A parameter table cont. 


Function 


70 

$46 

72 

$48 

74 

$4A 

76 

$4C 

78 

$4E 

80 

$50 

82 

$52 

84 

$54 

88 

$58 

90 

$5A 

92 

$5C 

94 

$5E 

96 

$60 

98 

$62 

100 

$64 

102 

$66 

104 

$68 

106 

$6A 

108 

$6C 

112 

$70 

114 

$72 

116 

$74 

118 

$76 


Font status 

l_solid, O_proportional or variable 
X coordinate of character in font form 

Y coordinate of character in font form (typically 0) 

X coordinate of character on screen 

Y coordinate of character on screen 
Character width 

Character height 

Pointer to start of font data (font form) 

Width of font form 

Style bit 0_Thicken, bit 1 _lighten, bit 2_skew 
bit 3_underline (ignored), bit 4_outline 
Lighten text mask 
Skew text mask 

Text thickening additional width 
Offset above character baseline for skew 
Offset below character baseline for skew 
Scaling flag 0_no scaling 

Character rotation vector. 0_horizontal 900_vertically down etc. 

.Text foreground colour 

.Special effects buffer pointer 

.Scaling buffer offset in above buffer 

.Text background colour (RAM VDI only) 

Copy raster form type flag (RAM VDI only) 

0_opaque type, n-plane source to n-plane destination bitblt 
write mode 

<>0_transparent type single plane source to n-plane dest 
VDI write mode 

Abort fill routine pointer (Function not available on disk based 
versions of TOS) 
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Undocumented Line-A variables 


The Line-A variables table contains other parameters that may be of use to 
the programmer. I refer to these variables as 'undocumented' although Atari do 
in fact list the variables in their reference material. These variables may change 
although it is unlikely. 


Function 


-46 

$D2 

-44 

$D4 

-42 

$D6 

-40 

$D8 

-38 

$DA 

-36 

$DC 

-34 

$DE 

-30 

$E2 

-28 

$E4 

-26 

$E6 

-24 

$E8 

-23 

$E9 

-22 

$EA 

-18 

SEE 

-16 

$F0 

-14 

$F2 

-12 

$F4 

-10 

$F6 

-6 

$FA 


-04 $FC 


Pixel cell height. (Same as font form's height) 

Maximum number of cells across -1 (X) 

Maximum number of cells high -1 (Y) 

Byte offset next vertical cell. Screen width (byte)*Pixel cell height 
Physical colour index of background color. 

Physical colour index of foreground color. 

Current cursor address 

Byte offset from screen base to top of first cell 

Cursor position: cell x 

Cursor position: cell y 

Cursor flash interval (in frames) 

Cursor countdown timer 

Address of monospace font data. Each cell is 8 pixels wide and 
byte aligned. The data format is defined in the VDI chapter. 
The cells may be arbitrarily high. 

Last ascii code in font 

First ascii code in font 

Width of font form in bytes 

Maximum x pixel value 

Address of font offset table (per VDI spec) 

Alpha text status byte 

bit 0 cursor flash 0:disabled l:enabled 
bit 1 flash state 0:off Lon 
bit 2 cursor visibility 0:invisible Lvisible 
bit 3 end of line 0:overwrite Lwrap 
bit 4 reverse video 0:on l:off 
bit 5 cursor position saved 0:false l:true 
Maximum y pixel value of the screen 
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Sprite definition block 


0 

$00 

X offset of hot-spot 


2 

$02 

Y offset of hot-spot 


4 

$04 

Format flag 


6 

$06 

Background \ Colour 


8 

$08 

Foreground / table index 

10 

$0A 

Interleaved 

\ Background line 0 

12 

$0C 

background / foreground 
image of 32 words 

1 Foreground line 0 

74 

76 

$4A 

$4C 

/ Foreground line 16 


Format flag 


+ve 

-ve 

Colour 

plotted 

Fg 

Bg 

Fg 

Bg 

0 

0 

0 

0 

Transparent 

0 

1 

0 

1 

Background 

1 

1 

1 

1 

Foreground 

1 

0 



Foreground 



1 

0 

XOR screen 


Memory form definition block (MFDB) 


0 

$00 

Memory pointer 

4 

$04 

Width 

8 

$08 

Height 

12 

$0C 

Word width 

16 

$10 

Format flag 

20 

$14 

Memory planes 

24 

$18 


28 

$1C 


32 

$20 


36 

$24 



32-bit address of pixel 0,0 
\ Raster area 
/ dimensions 
Pixel width/word size 
l=standard, 0=device specific 
Number of planes in raster area 
\ Three 
I reserved 
/ words 
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Header blocks 


Cartridge header block 

Prefix to application header 

252 $FC Flag #$ABCDEF42 program/ data 

or #$FA52255F diagnostic 


Application header block 


0 

$00 

Next 

4 

$04 

Flag/ 

init 

8 

$08 

Run 

12 

$0C 

Time 

14 

$0E 

Date 

16 

$10 

Size 

20 

$14 

Name 

Run 

flag bit 

set: 


Link to next application 
Pointer to initialize code 
or run flag (MSB) 

Pointer to run code 
DOS-format \ Time/ date 

DOS-format / application created 

Application size 

Application name (NNNNNNNN.EEE) 


0, Run before interrupt vectors and memory initialized 

1, Run before GEMDOS initialized 

2, unused 

3, Run before disk boot 

4, unused 

5, Application is a desk accessory 

6, Not a GEM application. No AES calls 

7, Requires command line parameters before execution 
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MC 68000 Instruction Summary 


Appendix G 


MC68000 instruction summary 

Instruction summary G.2 

ABCD to ADD G.2 

ADDA to ANDX G.3 

AND to ANDI to SR G.4 

ASL to Bcc G.5 

BCHG to BTST G.6 

CHK to CMPI G.7 

CMPM to DBcc G.8 

DBT to DIVU G.9 

EOR to ILLEGAL G.10 

JMP to LINK G.ll 

LSL to MOVE to CCR G.12 

MOVE to SR to MOVEM G.13 

MOVEP to NEG G.14 

NEGX to ORI to SR G.15 

PEA to SR to ROXL G.16 

ROXR to SBCD G.17 

ScctoSUBQ G.18 

SUBX to TRAPV G.19 

TST to UNLK G.20 

Address Mode BASIC equivalents G.21 

Allowable address mode types G.22 

Data storage G.23 

Data types G.24 

Byte, word and longword G.24 

BCD and BIT data types G.24 

Internal registers G.25 

Data registers G.25 

Address registers G.25 

Stack pointer G.26 

Program counter G.26 

Status register G.26 

User byte G.26 

System byte G.27 

Organization of addresses in memory G.27 
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INSTRUCTION SUMMARY 


Each Motorola MC68000 instruction is presented, many in terms of 
equivalent BASIC Instructions or assembler routines. The similes are for 
clarification of the use of each instruction; there is no access to the data or address 
registers (Dn or An respectively) or the condition codes from BASIC and 
therefore the examples which make use of these registers, and most of the 
effective address modes (ea), cannot be taken literally. 

Instructions 


ABCD: Add Binary Coded Decimal with Extend. Add two byte-sized binary 
coded decimal numbers and the Extend bit; a dollar sign is used to indicate a 
BCD number. Clear the extend bit and set the zero bit before performing this 
instruction which is limited to byte-size data register operations; multibyte 
additions are performed more easily in memory. 


BCD addition 


$ 7 

ABCDSL6 

$13 


$27 

ABCD $16 
$43 


DATA Register 
Addition 
Byte only 

ABCD D0,D1 


Memory 

Multibyte Addition 
MOVE #4,CCR 
ABCD -(A0),-(A1) 
ABCD -(A0),-(A1) 
ABCD -(A0),-(A1) 


Note that the z-flag is cleared if the result is non-zero, otherwise it is 
unchanged and that in memory additions the data must be stored with the most 
significant digit lower in memory and the address pointers initially set to the byte 
above the low order BCD digit in memory, as the only available addressing mode 
is predecrement. 


ADD: Add two integers, one of the integers must be the contents of a data 
register. 


LET Dn = Dn + ea ADD ea,Dn 

LET ea = ea + Dn ADD Dn,ea 

Use ADD ea,Dn where the destination is a data register. 
Use ADDA where the destination is an address register. 
Use ADDI or ADDQ where the source is immediate data 
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ADDA: Add the contents of the effective address to the contents of the 
destination address register. 

LET An = An + ea ADDA ea,An 

ADDI: Add a constant value to the contents of the destination effective 
address. Use ADDQ for speed and small integers. 

LET ea = ea + 999 ADDI #999,ea 

ADDQ: Add a constant in the range of 1 to 8 to the contents of the effective 
address. Faster addition than ADDI. 

LET ea = ea + 8 ADDQ #8,ea 

ADDX: Add either register to register, or predecremented memory to 
memory, with extend. Use of the extend bit enables multiprecision arithmetic to 
be performed, the extend bit acting as a carry between successive operations. 

Data register addition 
Add two 64 bit integers 
D0_D1 and D2_D3 Lo-Hi resply 
ADD.L D0,D2 Low bits 
ADDX.L D1,D3 High bits 

Memory addition 
MOVE #4,CCR 
ADDX.L ~(A0),-(A1) 

ADDX.L -(A0),-(A1) etc. 

Note that the z-flag is cleared if the result is non-zero, otherwise it is 
unchanged. For memory additions first clear the Extend bit and set the Zero flag. 
The data must be stored with the most significant digit lower in memory and the 
address pointers initially set the operand size above the low order digit in as the 
only addressing mode is predecrement. 


Memory additions 
ADDX -(Ay), -(Ax) 

Where X infers the Extend bit 
LET Ay = Ay - 4 
I FT Ax = Ax - 4 
POKE(Ax), PEEK(Ax) + 

PEEK(Ay) + X 
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AND: AND the source operand to the destination operand. The source AND 
data is normally used either (a) as a mask enabling a portion of the destination 
operand to be examined (bits are masked by l's in the source); or (b) to clear bits 
by setting the corresponding bit in the source to a zero. 

LET ea = Dn && ea AND Dn,ea 

LET Dn = src && Dn AND ea,Dn 

If src = 3, then AND src keeps bits 0 and 1 in Dn only, the others are set to 
zero. 

Use AND ea,Dn where the destination is a data register. 

Use ANDA where the destination is an address register. 

Use ANDI where the source is immediate data. 

ANDI: ANDI the immediate data to the destination effective address. 

LET ea = data && ea ANDI.W #512,D0 

Keep bit 9 of word only 

ANDI to CCR: ANDI the data to the condition code register. 

LET CCR = 26 && CCR ANDI #26,CCR 

Normally bits can be tested via the condition codes without using the AND 
function as a mask. Here it is used to zero a bit position where there is a zero in 
the AND data; that is zero and carry (bits 0 and 2 in the CCR) are cleared. 

ANDI to SR: ANDI the data to the status register is a privileged instruction 
and attempted access while in user mode will trap to the privilege violation 
exception vector. 

LET SR = 63743 && SR ANDI #63743,SR 

Set the interrupt mask level to zero and leave unchanged the condition code 
and system flags. 
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ASL: Arithmetically Shift Left the bits of the operand. The last MSB shifted 
sets the carry and extend bits; the LSB is set to zero each shift. The overflow bit is 
set if the sign is changed during the shift and is used to flag a change of sign. The 
instruction is used for fast multiplication of *2 and *4; other values should use 

MULS MSB LSB 


XJOr 


0 


LET ea = ea * 2 ASL ea (shift 1) 

LET Dy = Dy * (2 A Dx) ASL Dx,Dy (reg modulo 64) 

LET Dy = Dy * (2 A 5) ASL #5,Dy (shift 1 to 8) 

The carry bit is cleared if the shift count is zero. 


ASR: Arithmetically Shift Right the bits of the operand. The MSB sign bit is 
retained; the last LSB shifted is used to set the carry and extend bits. This 
instruction can be used for rapid integer division by 2, 4, 8 of signed numbers; 
use DIVS for other divisions. . „ _ _ 

MSB LSB 

+t - ■ » 

t 


Sign 

bit 


LET ea = INT(ea/2) ASR ea (shift 1) 

LET Dy = INT(Dy/(2 A Dx) ASR Dx,Dy (reg modulo 64) 

LET Dy = INT(Dy/(2 A 5) ASR #5,Dy (shift 1 to 8) 

The carry bit is cleared if the shift count is zero. 


Bcc: Branch on condition a two's complement displacement from the current 
program counter position (Instruction address + 2) +126 to -128 for a short branch 
or +32766 to -32768 for a word branch operation, the condition cc may be: 


Conditions 

Two's complement 
arithmetic 

EQ Equal To CS Carry Set 

NE Not Equal CC Carry Clear 

MI Minus VS Overflow 

PL Plus VC No Overflow 

HI Higher Than 

LS Lower Than or same 

GT Greater Than 
LT Less Than 
GE Greater Than 

or Equal to 
LE Less Than or 
Equal to 


IF Dn = 0 THEN GOTO yy BEQ #14 

IF Dn 0 THEN GOTO label BGT label 
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BCHG: A bit is tested and its state reversed. If the bit was zero before the test; 
that is clear, then the Zero flag is set, otherwise it is cleared. 

IF BITn = 0 THEN set_Zflag: 

ELSE clear_Zflag BCHG #6,ea (data modulo 8) 

LET BITn = 1 - BITn BCHG Dn,ea (reg modulo 32) 

BCLR: A bit is tested and then cleared. If the bit was zero before the test; that 
is clear, then the Zero flag is set, otherwise it is cleared. 

IF BITn = 0 THEN set_Zflag: 

ELSE clear_Zflag BCLR #6,ea (data modulo 8) 

LET BITn = 0 BCLR Dn,ea (reg modulo 32) 

BRA: BRanch Always, a two's complement displacement branch either of 
+126 to -128 bytes by a single word instruction or of +32766 to -32768 bytes by a 
two-word instruction from the current program counter position (instruction 
address + 2). 

GOTO label BRA label 

GOTO 1275 BRA #8 

BSET: A bit is tested and then set. If the bit was zero before the test; that is 
clear, then the Zero flag is set, otherwise it is cleared. 

IF BITn = 0 THEN set_Zflag: 

ELSE clear_Zflag BSET #6,ea (data modulo 8) 

LET BITn = 1 BSET Dn,ea (reg modulo 32) 

BSR: Branch to SubRoutine, either a two's complement displacement of +126 
to -128 bytes by a single-word instruction, or of +32766 to -32768 bytes by a 
two-word instruction, from the current program counter position (instruction 
address +2). Return to the next instruction via an RTS from the subroutine. 

GOSUB label BSR label 

GOSUB 1275 BSR #8 

BTST: A bit is tested. If the bit was zero; that is clear, then the Zero flag is set, 
otherwise the Zero flag is cleared. 

IF BITn = 0 THEN set_Zflag: BTST #6,ea (data modulo 8) 

ELSE clear_Zflag BTST Dn,ea (reg modulo 32) 
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CHK: Check a data register low-order word against the two's complement 
upper bound of the source operand. If the register value is less than zero or 
greater than the test value, then jump to the CHK Trap exception vector. 

IF Dn > ea OR CHK ea,Dn 

Dn < 0 THEN GOSUB chk_trap 

CLR: Clear an operand sets all or part of a specified address or register to 
zero. 


LET ea = 0 CLR ea 

MOVEQ #0,Dn is quicker than CLR.L Dn 

SUBA.L An,An is quicker for memory applications 

CMP: The compare instructions are used exclusively to set the condition code 
registers for a subsequent conditional operation. The comparison is made by 
subtracting the source operand from the destination operand and setting the 
condition codes accordingly; neither operand is altered by the instruction. 

CMP ea,Dn 

IF ea = Dn THEN GOTO loop BEQ loop 

Use CMPA when the destination is an address register. 

Use CMPI when the source is immediate data. 

Use CMPM for memory to memory comparisons. 

CMPA: Subtract the source operand from the address register and set the 
condition code flags accordingly. The comparison is based on a sign-extended 
source if it is a word operand. The address register is not altered. 

CMPA ea,Dn 

CMPI: Subtract the immediate operand from the effective address operand 
and set the condition code flags accordingly; neither operand is altered. Use TST 
for comparing with zero as it is much quicker. 


CMPI #999,ea 
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CMPM: Subtract the contents of the memory address pointed to by the 
source address register from the contents of the memory address pointed to by 
the destination register and set the condition code flags accordingly. Increase the 
value of both address registers by the size of the operand (1, 2 or 4 byte word and 
longword respectively). 

The main use for this instruction is comparing strings 

LET Dn = length_string - 1 

loop 

IF PEEK (Ay) <> PEEK (Ax) THEN 
Ay = Ay + s : Ax = Ax + s 
GOTO not_same 

ELSE 

Ay = Ay + s : Ax = Ax + s 
LET Dn = Dn -1 
IF Dn = -1 THEN GOTO loop 

same not_same 


loop CMPM (Ay)+,(Ax)+ 
BNE not_same 
DBRA Dn,loop 

same 


not_same Dn is the character count, s=operand size 

DBcc: Test the condition and exit loop to the next instruction if the condition 
is met. If the condition is not met, then decrement the low order 16 bits of the 
count data register. If the count becomes -1, then exit loop and carry on with the 
next instruction, otherwise branch the two's complement displacement of the 
following word -32766 to +32768 from the current program counter position 
(instruction address +2). The test may be one of the following: 


Conditions 

Two's complement 
arithmetic 

EQ Equal To CS Carry Set 

NE Not Equal CC Carry Clear 

MI Minus VS Overflow 

PL Plus VC No Overflow 

HI Higher Than 

LS Lower Than or same 

GT Greater Than 
LT Less Than 
GE Greater Than 

or Equal to 
LE Less Than or 
Equal to 


DBEQ DO, loop BEQ pass 

SUB #1,D0 

(Equivalent) BPL loop 

pass . 
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DBT: Always branches and is of little use. 

DBRA: Sometimes written DBF, it makes the branch based on the data 
register count only and branches when the count reaches -1. Therefore the count 
should be initialised to the required count -1. If the loop is entered via a jump or 
branch at the DBcc instruction, then the count is the required count and usefully 
an initial zero count will cause an immediate exit from the loop. 

DIVS: Sign Divide a 32-bit data register destination operand by a 16 bit 
source operand and store the integer result in the lower 16 bits of the destination 
register, the remainder is stored in the upper 16 bits of the destination and keeps 
the dividend sign. Division by zero causes a jump to the Divide-by-Zero Trap 
exception vector. On overflow, the result is larger than 16 bits, the V-flag is set 
and the operation terminated without affecting either operand. 

LET Dn = Dn / ea DIVS ea,Dn 

ASR ea is a fast signed divide by two 
MOVEQ #2,D2 

ASR D2,Dx is a quicker divide by four 

Generally use DIVS and DIVU for division by a prime number, otherwise 
think of an alternative as the division instruction, because of its general nature, is 
not quick. 

DIVU: Unsigned arithmetic divide of a 32-bit data register destination 
operand by a 16-bit source operand. The integer result is stored in the lower 16 
bits of the destination register and the remainder in the upper 16 bits. Division by 
zero causes a jump to the Divide-By-Zero exception vector. On overflow the 
result is larger than 16 bits, the V-flag is set and the operation terminated without 
affecting either operand. 


LET Dn = Dn / ea 


DIVU ea,Dn 
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EOR: EOR the data register source operand to the contents of the destination 
operand. The source EOR data is normally used to invert the state of a bit or bits. 

LET ea = Dn AA ea EOR Dn,ea 

If Dn=3, then bits 0 and 1 in the effective address are inverted. 

Use EORI where the source is immediate data. 

There is no memory to data register operation. 

EORI: EORI the immediate data to the destination effective address. 

LET ea = data AA ea EORI.B #16,D0 

Invert bit 4 of DO 

EORI to CCR: EORI the immediate data to the condition code register. 

LET CCR = 4 AA CCR EORI #4,CCR 

Toggle the Zerojlag 

EORI to SR: EORI the immediate data to the status register. This is a 
privileged instruction and attempted access while in user mode will cause a trap 
to the privilege violation exception vector. 

LET SR = 8192 AA SR EORI #8192,SR 

Toggle the supervisor bit 

EXG: Exchange the longword contents of two registers. Referred to in many 
BASICs as SWAP, which has a different meaning in the MC68000 instruction 
code. 

LET tmp=D0 : D0=D1 : Dl=tmp EXG D0,D1 

LET tmp=A0 : A0=A1 : Al=tmp EXG A0,A1 

LET tmp=D0 : D0=A0 : A0=tmp EXG D0,A0 

EXT: Sign-extend a data register contents, a byte to a word or a word to a 
longword, to permit operations involving mixed size data to take place. 

EXT Dn 

ILLEGAL: The illegal instruction causes the processor to jump to the illegal 
instruction trap exception process subroutine. 

GOSUB Ill_Trap ILLEGAL 
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JMP _JSR: JMP and JSR are long forms of BRA and BSR, the main difference 
being the jump instruction's ability to access any part of memory whereas the 
branch instructions are limited to a relative +/-32K bytes jump. 

JMP: Jump to a routine in memory specified by the effective address, either 
absolute or relative to the current program counter position. 

GOTO ea JMP ea 

JSR: Jump to a subroutine in memory specified by the effective address, 
either absolute or relative to the current program counter position 

GOSUB ea JSR ea 

LEA: Load Effective Address loads a calculated effective address into an 
address register. The calculated address can be the sum of two registers, one 
must be an address register, and a displacement which provides the addition of 
two registers and a displacement without affecting either register, in a single 
instruction. 


LET An = Start_of_text_address LEA text,An 

LET An = Start_of_table LEA tabl,An 

LET AO = A1 + D2 +64 LEA 64( A1 .D2),A0 

LINK: LINK enables a block of memory, part of the stack, to be temporarily 
reserved for a specific purpose; that is an index table, a text string, an array etc. 
and the space recovered when the requirement has passed. 

DIM A(64) LINK An, #-64 

Saves a block of 64 bytes in memory. The original value of An is preserved on 
the stack and will be recovered on UNLK. The current value of An is the start of 
the data space which may be most easily accessed via indirect with displacement 
or indirect with index addressing modes. 
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LSL: Logically Shift Left the bits of the operand. The MSB sets the carry and 
extend bits, the LSB is set to zero. 

MSB LSB 

7/G— 


The carry bit is cleared if 
the shift count is zero. 


0 


LET ea = ea * 2 
LET Dy = Dy * (2 A Dx) 
LET Dy = Dy * (2 A 5) 


LSL ea (shift 1) 

LSL Dx,Dy (reg modulo 64) 
LSL #5,Dy (shift 1 to 8) 


LSR: Logically Shift Right the bits of the operand. The MSB is set to zero and 
the LSB sets the carry and extend bits. 


The carry bit is cleared if 
the shift count is zero 0 

LET ea = INT(ea/2) 

LET Dy = INT(Dy/(2 A Dx) 
LET Dy = INT(Dy/ (2 A 5) 


MSB LSB 


x/q 


LSR ea (shift 1) 

LSR Dx,Dy (reg modulo 64) 
LSR #5,Dy (shift 1 to 8) 


MOVE: Move the byte, word or longword contents of the source effective 
address to the destination effective address. 

MOVE ea,ea 

LET D1 = DO MOVE D0,D1 

LET SP = SP-4 : POKE(SP),D7 MOVE D7,-(SP) 

POKE(SP),D7 : LET SP = SP+4 MOVE (SP)+,D7 


Use MOVEA where the destination is an address register. 


MOVE from SR: Save the word contents of the status register in the effective 
address register or memory location. ** Be careful as this instruction is privileged 
in the MC68010 and MC68020 instruction sets, programers should try not to use it 
in user state. 

MOVE SR,ea 

LET DO = PEEK_W(SR) MOVE.W SR,D0 

MOVE to CCR: Move the contents of the source operand WORD into the 
condition code register. Only the low-order byte is used; the upper byte is 
ignored. 

MOVE ea,CCR 

POKE_W(CCR),4 MOVE #4, CCR 


Set the Zero flag and clear all others. 
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MOVE to SR: Move the contents of the source operand into the status 
register. This is a privileged instruction and attempted access while in user mode 
will cause a trap to the privilege violation exception vector. 

MOVE ea,SR 

POKE_W(SR),1792 MOVE #1792,SR 

Clear all flags, set user state, and set interrupt mask to level seven. 

MOVE USP: Move the contents of the user stack pointer to or from the 
specified address register. This is a privileged instruction and attempted access 
while in user mode will cause a trap to the privilege violation exception vector. 

LET A3 = USP MOVE USP, A3 

LET USP = A3 MOVE A3, USP 

MOVEA: Move the contents of the source effective address to the destination 
address register. Byte-sized operations are not permitted. 

LET A3 = PEEK_W(192) MOVEA.W 192, A3 

LET AO = PEEK_L(4) MOVEA.L 4,A0 

MOVEM: Move multiple registers to or from memory which permits the 
transfer of a block of specified registers to and from memory in a predetermined 
sequence by one instruction. 

LET A7=A7-4 : POKEJL(A7),DO MOVEM.L #57344,-(A7) 

LET A7=A7-4 : POKE_L(A7),Dl 
LET A7=A7-4 : POKE_L(A7),D2 

MOVEM.L (A7)+,#1860 

Either of these instructions save registers DO, D1 and D2 

MOVEM.L # 7,24(A7) 
or MOVEM.L #57344,-(A7) ** 

and to recover the registers DO, D1 and D2 either 

MOVEM.L 24(A7),#7 
or MOVEM.L (A 7)+,#7 

** The predecrement mode of addressing values the registers in reverse order 
for the register list mask (DO - bit 15, A 7 - bit 0), permitting push-on, pull-off on a 
last in-first out basis. 
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MOVEP: Move data to or from a data register and alternate bytes in memory, 
enabling the MC68000 to interface with 8-bit peripheral devices. The data is 
transferred on either the high half of the data bus D8-D15, even addresses, or the 
low half D0-D7, odd addresses, to memory occupying alternate bytes in the 
processor's memory map. The data is transferred in high-low order. 

POKE_W (7 +65536),Dn MOVEP Dn,d(Ay) 

LET Dn = PEEK_W(7+65536) MOVEP 7(Ay),Dn 

This is the ONLY instruction that provides word and longword access at odd 
addresses. 

MOVEQ: Move sign-extended 32-bit immediate data in the range of +127 to 
-128 to a data register. A fast means of loading small positive and negative 
integers into a data register. 

LET DO = 0 MOVEQ #0,D0 

MULS: Multiply two signed 16-bit operands. Only the low-order 16-bits are 
used from both operands for the multiplication, the result being the 32-bit 
product in the destination data register. 

MULS ea,Dn 


ASL ea is a fast signed multiply by two. 

MULU: Multiply two unsigned 16-bit operands. Only the low- order 16-bits 
are used from both operands for the multiplication, the result being the 32-bit 
product in the destination data register. 

MULU ea,Dn 

NBCD: Negate Decimal with Extend subtracts the destination byte-sized 
operand and the extend bit from zero using decimal arithmetic. 

NBCD ea 

Extend bit clear, the ten's complement is produced. 

Extend bit set, the one's complement is produced. 

NEG: Negate subtracts the destination operand from zero, producing the 
two's complement of a byte, word or longword operand. 

NEG ea 
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NEGX: Negate with extend subtracts the destination operand and the extend 
bit from zero, producing the two's complement of a byte, word or longword 
operand. 

NEGX ea 

NOP: No OPeration has no effect other than to increment the program 
counter by 2. Its use is generally either for creating a space in code which may be 
used later on for adding a subroutine call, for writing text etc. or for deleting 
parts of code, especially test routines, without the need for recompiling. 

NOP 

NOT: Logically complement, producing the one's complement of the 
operand. 

NOT ea 

OR: Or the source to the contents of the destination data register. The source 
OR data is normally used to set specific bits of an operand. 

LET Dn = src II Dn OR ea,Dn 

If src = 3, then OR src sets bits 0 and 1 in Dn; the other bits are left unchanged. 

Use OR ea,Dn where the destination is a data register. 

Use ORI where the source is immediate data. 

ORI: ORI the immediate data to the destination effective address. 

ORI.W #512, DO 

LET ea = data I I ea Set bit 9 of word, others unchanged 

ORI to CCR: ORI the data to the condition code register. 

LET CCR = 511 CCR ORI #5, CCR 

OR is used to set bit positions; that is Zero and Carry (Bits 0 and 2 in the 
CCR) are set, the others are unchanged. 

ORI to SR: ORI the data to the status register 

LET SR = 1792 I I SR ORI #1792,SR 

Set the status register interrupt mask to level seven, all other conditions 
unchanged. This is a privileged instruction and attempted access from user mode 
will cause a trap to the privilege violation exception process routine. 
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PEA: Push effective address pushes a longword-computed address onto the 
current stack. It is useful for passing parameters to a subroutine which are 
accessed via an address register indirect with displacement instruction, the 
parameter may be removed from the stack prior to return if necessary. 

PEA param 

JSR sprog 

Access parameter sprog MOVEA.L 4(SP),A0 

Tidy stack MOVE.L (SP)+,(SP) 

RTS 

RESET: Reset external devices by asserting the reset line. There is no affect on 
the processor other than an increase of two in the value of the program counter. 
This is a privileged instruction and attempted access while in user mode will 
cause a trap to the privilege violation exception vector. 

RESET 

ROL: ROtate without extend Left. The MSB is rotated to the LSB and the 
carry; the other bits are shifted up one. The carry bit is set to the extend bit for a 

shift count of zero 

ROL ea (shift 1) 

ROL Dx,Dy (reg modulo 64) 

ROL #5,Dy (shift 1 to 8) 

ROR: ROtate without extend Right. The LSB is rotated to the MSB and the 
carry; the other bits are shifted down one. The carry bit is set to the extend bit for 

a shift count of zero. 

ROR ea (shift 1) 

ROR Dx,Dy (reg modulo 64) 

ROR #5,Dy (shift 1 to 8) 

ROXL: ROtate with extend Left. The MSB is rotated to the extend bit and the 
carry, the extend bit is rotated to the LSB and the other bits are shifted up one. 

The carry bit is set to the extend 
bit for a shift count of zero. 

ROXL ea (shift 1) 

ROXL Dx,Dy (reg modulo 64) 

MSB LSB ROXL #5,Dy (shift 1 to 8) 





MSB LSB 
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ROXR: ROtate with extend Right. The LSB is rotated to the extend bit and 
the carry, the extend bit is rotated to the MSB and the other bits are shifted down 
one. The carry bit is set to the extend bit for a shift count of zero. 



— X/C 

ROXR ea (shift 1) 

ROXR Dx,Dy (reg modulo 64) 

MSB 

LSB 

ROXR #5,Dy (shift 1 to 8) 


RTE: Return from Exception. The status register and the program counter are 
pulled from the current (supervisor) stack* This instruction is privileged and 
attempted access while in user mode will cause a trap, to the privilege violation 
exception vector. 

(SP)+,SR RTE 

(SP)+,PC 

RTR: Return and Restore. The condition code and then the program counter 
are pulled from the current stack. 


(SP)+,CCR RTR 
(SP)+,PC 

RTS: Return from Subroutine. The program counter is pulled from the 
current stack. 


(SP)+,PC RTS 

SBCD: Subtract Decimal with Extend. Subtrract a byte-sized binary coded 
decimal number and the extend bit from the destination operand byte using 
decimal arithmetic and store the result in the destination location. 

BCD subtraction Memory 

Multibyte Subtraction 

SBCD $ 7 SBCD $27 

Sl£ $16 MOVE #4,CCR 

$1 $11 SBCD D0,D1 

Note that the z-flag is cleared if the result is non-zero, otherwise it is 
unchanged. For memory additions the data must be stored with the most 
significant digit lower in memory and the address register pointers initially set to 
the byte above the low-order BCD digit. The only memory addressing mode is 
predecrement. 
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See: Set according to condition. The specified condition is tested and the byte 
specified set to all ones if true or all zeros if false. The condition may be: 


Conditions 

Two's complement 
arithmetic 

EQ 

Equal To 

CS 

Carry Set 

GT 

Greater Than 

NE 

Not Equal 

CC 

Carry Clear 

LT 

Less Than 

MI 

Minus 

VS 

Overflow 

GE 

Greater Than 

PL 

Plus 

VC 

No Overflow 


or Equal to 

HI 

Higher Than 

T 

True 

LE 

Less Than or 

LS 

Lower Than 

F 

False 


Equal to 


or same 






See ea 


STOP: Load the status register and Stop. The immediate operand is put into 
the status register and the program counter advanced to the next instruction and 
then stopped. Execution only resumes when a trace, interrupt or reset exception 
occurs. 

STOP #7 

SUB: Subtract the source from the destination. One of the integers must be 
the contents of a data register. 

LET Dn = Dn - ea SUB ea,Dn 

LET ea = ea - Dn SUB Dn,ea 

Use SUB ea,Dn where the destination is a data register. 

Use SUBA where the destination is an address register. 

Use SUBI or SUBQ where the source is immediate data. 

SUBA: Subtract the contents of the effective address from the contents of the 
destination address register. 

LET An = An - ea SUBA ea,An 

SUBI: Subtract a constant value from the contents of the destination effective 
address. Use SUBQ for speed and small integers. 

LET ea = ea - 999 SUBI #999,ea 

SUBQ: Subtract a constant of from 1 to 8 from the contents of the effective 
address. Faster subtraction than SUBI. 

LET ea = ea - 8 SUBQ #8,ea 
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SUBX: Subtract either register to register, or predecremented memory from 
memory, with extend. The extend bit enables multiprecision arithmetic to be 
performed, acting as a borrow between successive operations. 

Data register subtractions 
Subtract two 64 bit integers 
D0_D1 and D2_D3 Lo-Hi resply 
SUB.L D0,D2 Low bits 
SUBX.L D1,D3 High bits 

Memory subtractions 
MOVE #4,CCR 
SUBX.L -(A0),-(A1) 

SUBX.L -(A0),-(A1) 

Note that the z-flag is cleared if the result is non-zero, otherwise it is 
unchanged. For memory additions first clear the Extend bit and set the Zero flag. 
The data must be stored with the most significant digit lower in memory and the 
address pointers initially set the operand size above the low order digit. 
Predecrement is the only memory addressing mode. 

SWAP: Swap register halves exchanges the high-order word of a data 
register with the low-order word. This instruction provides access to the 
low-order byte of the high word. 


Memory subtractions 
SUBX -(Ay),-(Ax) 
where X infers Extend bit 
LET Ay = Ay - 4 
LET Ax = Ax - 4 
POKE(Ax),PEEK(Ax) - 

PEEK(Ay) - X 


Dn 0-15 < — > Dn 16-31 

TAS: Test and set an operand, compares the operand byte with zero and sets 
the condition codes accordingly. If the byte is zero, the Z_flag is set; if the MSB is 
non-zero, then the N_flag is set. The MSB of the operand is then set. 

TAS ea 

TRAP: Trap. The processor commences execution at the relevant trap 
exception vector address. 


TRAP #n 

TRAPV: Trap on Overflow. The processor commences execution at the trap 
on overflow exception vector address. 


TRAPV 
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TST: Test an operand. The operand is compared with zero and the condition 
codes set accordingly. 


TST ea 


Use in preference to CMPI #0,ea 

UNLK: Unlink. The stack pointer is loaded from the specified address 
register; the address register is then loaded with the longword pulled from the 
top of the stack and the linked space deallocated. 

UNLK An 


Key 


&& bitwise AND 

AA bitwise EOR 

I I bitwise OR 
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Address mode 


Assembler language and BASIC equivalents 


Address Mode 

Source 

Destination 

Data register Dn 

direct 

MOVE.L D2,D0 
LET DO = D2 

MOVE.L #999,D0 
LET DO = 999 

Address register An 
direct 

MOVE.L AO, DO 
LET DO = AO 

MOVEA.L #999, A0 
LET A0 = 999 

Address register (An) 
indirect 

MOVE.L (AO), DO 
LET D0,PEEK L(A0) 

MOVE.L #999,(A0) 
POKE L (A0),999 

Address register (An)+ 
indirect with 
postincrement 

MOVE.L (AO)+,DO 
LET D0,PEEK L(A0) 
LET AO = AO + 4 

MOVE.L #999,(A0)+ 
POKE L (A0),999 
LET A0 = A0 + 4 

Address register -(An) 
indirect with 
predecrement 

MOVE.L -(AO),DO 
LET AO = AO - 4 
LET D0,PEEK L(A0) 

MOVE.L #999,-(A0) 
LET A0 = A0 - 4 
POKE L (A0),999 

Address register d(An) 
indirect with displacement 

MOVE.L 9(A0),D0 
LET DO = PEEK L(9 + AO) 

MOVE.L #999,9(A0) 
POKE L(A0+9),999 

Address register d(An.Ri) 
indirect with index 

MOVE.L 9(A0.D2),D0 MOVE.L #999,9(A0.D0) 
LET D0=PEEK_L(9+A0+D2) POKE_L(AO+9+DO),999 

Absolute short Sxxxx 
ABS.S 

MOVE.L 1024, DO 
LET DO = PEEK L(1024) 

MOVE.L #999,1024 
POKE L(1024),999 

Absolute long $xxxxxx 
ABS.L 

MOVE.L 163840, DO 
LET DO=PEEK L(163840) 

MOVE.L #999,163840 
POKE L(163840),999 

Program counter d(PC) 
with 

displacement 

MOVE.L 9(PC),D0 

LET D0=9 + Contents of Not legal 

Program Counter 

Program counter d(PC.Ri) 

with 

index 

MOVE.L 9(PC.D2),D0 
LET D0=9+D2+Contents of Not legal 

Program Counter 

Immediate #$xxx 

Imm 

MOVE.L #65536,D0 
LET DO = 65536 

Not legal 

Notes 

Register DO is used 
for the destination 
as an example; any 
other valid effective 
address may be used. 

The source is defined 
as immediate data 
value 999; any other 
valid effective 
address may be used. 


All equivalents have been defined as having longword operands, byte and 
word-sized operands may also be used. 
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Allowable address mode types 



All 

Alt 

Mem 

Add 

Dat 

Alt 

Add 

Alt 

Add 

Mod 

Dat 

Add 

Mdl 

Dat 

Add 

Md2 

Con 

Add 

Mdl 

Con 

Alt 

Add 

Con 

Add 

Md2 


Srce 

Dest 

Dest 

Dest 

Srce 

Dest 


Dest 

Srce 

Dn 

X 


X 

X 

X 

X 

X 




An 

X 




X 






(An) 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

(An)+ 

X 

X 

X 

X 

X 

X 

X 



X 

-(An) 

X 

X 

X 

X 

X 

X 

X 


X 


d(An) 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

d(An.Ri) 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

ABS shrt 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

ABS long 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

d(PC) 

X 





X 

X 

X 


X 

d(PC.Ri) 

X 





X 

X 

X 


X 

Imm 

X 





X 






ADD 

ADD 

ADDI 

NBCE 

ADDC 

)AND 

BTST 

JMP 

MOV] 

:m 


ADDA 

AND 

ANDI 

NEG 

SUBQ 

CHK 


JSR 

reg 

MOVEM 


CMP 

OR 

BCHC 

NEGX 


DIVS 


LEA 

to 

mem 


CMPA 

SUB 

BCLR 

NOT 


DIVU 


PEA 

mem 

to 


MOV] 

l 

BSET 

ORI 






reg 

1 

lOVE/ 

ASL 

CLR 



MOVI 






SUB 

ASR 

CMPI 

See 


toCCI 

t 





SUBA 

ROXL 

EOR 



MOVI 






ROXR 

EORI 

SUBI 



to SR 






ROL 

MOV! 

:tas 









ROR 


TST 


MULE 







LSL 

MOVI 



MULt 

r 






LSR 

fr SR 



OR 







Alt = Alterable Mod = Mode Mdl = Model 
Mem = Memory Dat = Data Md2 = Mode2 
Add = Address Con = Control 


\ Types of addressing mode 
I definitions used by Motorola 
/ to describe allowable modes. 
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Data storage 

The MC68000 accesses two internal locations for storage: 

Internal registers, of which there are 17, store the data inside the 
microprocessor itself. They are very limited in the amount of data they can store, 
but provide extremely fast access. 

ST RAM/ROM, where data access is still quick, but not as fast as the internal 
register data access. 



Internal memory 
devices 


MC68000 processor 
internal register layout 
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Data types 

The MC68000 microprocessor supports five different data types; some 
instructions are limited to a specific data type, but mostly there is an allowable 
range with the default of a word. Where choice is not implicit, it is defined in the 
instruction word extension as either byte, word or longword. 

Byte, Word and Longword data types 


Word 

| MSB LSB| 

HIGH ORDER BYTE 

LOW ORDER BYTE 

31 23 15 7 0 


Byte 


HI MID ORDER BYTE LOW BYTE 


, HIGH BYTE 
[MSB 


LO MID ORDER BYTE 

Longword LSil 


BCD and BIT data types 

Bit data 

MSB LSB 

Byte I7I6I5I4I3I2I1I0I 


BCDO BCD 1 

MOST SIGNIFICANT LEAST SIGNIFICANT 
BCD DIGIT BCD DIGIT 
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Internal registers 


The Motorola 68000 has seventeen 32-bit registers, a 24-bit program counter 
and a 16-bit status register. Eight of the 32-bit registers (DO to D7) are used as 
data registers for operations involving single bit, BCD (4-bit), byte (8-bit), word 
(16-bit) and longword (32-bit) data. The remaining nine registers are split into 
two: seven of them (A0 to A6) act as address registers, and two act as stack 
pointers. Only one stack pointer may be accessed at a time, hence the convention 
of calling both of them A 7. The address register operations are based on words 
and longwords only. 

Data registers 

Data storage of byte, word and longword is always performed in the part of 
the data registers shown; unused parts of the register are not altered. 


DO 

D1 

D2 

D3 Eight data 

D4 registers 

D5 

D6 

D7 


31 16 15 8 7 0 







Bvte 





Word 



L 

Longword 








Address registers 

The address registers are used as pointers to user stacks, as base address 
registers and temporary storage for computed addresses that are not to affect the 
Status Register. Address storage is always performed in the part of the address 
register shown. When used as a destination operand, the entire address is 
changed regardless of the operation size. Address registers do not support 
byte-sized operations as either source or destination. Words are sign- extended to 
longwords before an operation is performed. 


31 16 15 8 7 0 









word 


L 

Longword 








A0 


A1 


A2 

Seven 

A3 

address 

A4 

registers 

A5 


A6 
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Stack pointer 

The user stack pointer typically saves subroutine returns when in user mode. 
The supervisor stack pointer points to a stack that saves the status register 
contents during trap and interrupt routines as well as the supervisor subroutine 
returns. Only one of the stack pointers is addressable at a time, so they are both 
called A7. Bytes pushed onto a stack are stored in the high order half of the word. 


A7 Two Stack 

A7 Pointers 


31 0 

User stack pointer 

Supervisor stack pointer 


Program counter 

The program counter provides the MC68000 with an address range of 16 
Megabytes. As instructions are based on word-sized operands, the counter must 
always hold an even address. Attempts to address odd-numbered locations will 
cause an error-trap. 

31 23 0 

OOOOOOOQ 


Status register 

15 87 0 


The status register is split into user and system bytes. The user byte is 
evaluated for the condition codes used in the branching instructions. The codes 
are affected by all instructions that alter the contents of the data registers or 
memory, but not by changes to the address registers. 


User byte 

Condition codes 

I x | x | x | 4 f3 T~2 | 1 | 0 | 

\ / 

Not used 


Bit 0 - Carry 
Bit 1 - Overflow 
Bit 2 - Zero 
Bit 3 - Negative 
Bit 4 - Extend 
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The unused bits in the status register are read as zero. They are reserved for 
the MC68020 instruction set. 


System byte 

1 151 x 1131 x I x 1101 9 I 8 | 

\ / 

Interrupt 

mask 


Bits 8-1 0 Interrupt mask (0-7) 
Bit 13 - Supervisor state 
Bit 15- Trace mode 


x = not used 


Organization of addresses in memory 



Memory top 


Any address 

+3 7-0 

+2 15-8 

+1 23-16 

- — Even address 31-24 


+1 

- — Even address 


Memory bottom 


For word and longword 
memory operations, the high 
byte is on a word boundary 
(even address), the following 
bytes are in order higher in memory. 


By convention, system stacks 
grow downwards in memory. 


Stack 
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MC 68000 Instruction Codes 


Appendix H 


MC68000 instruction codes 

General H.2 

Instruction word parsing analysis H.2 

Instruction codes H.4 

Bit manipulation, move peripheral and immediate 

instructions H.4 

Move byte instruction H.5 

Move longword instruction H.5 

Move word instruction H.5 

Miscellaneous instructions H.6 

Add Quick, subtract quick, set conditionally and 

decrement instructions H.7 
Branch conditionally instructions H.8 

Conditional tests H.8 

Move quick instructions H.9 

OR, divide and subtract decimal instructions H.9 

Subtract and subtract extended instructions H.9 

Emulation instruction, type 1010 H.10 

Compare, exclusive OR instructions H.10 

AND, multiply, add decimal, exchange instructions H.ll 
Add and add extended instructions H.ll 

Shift and rotate instructions H.12 

Emulation instructions, type 1111 H.13 

Address modes 

Encoding H.14 
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Motorola MC68000 Coding 

The Motorola MC68000 series of microprocessors rationalize instruction code 
allocation by segmenting the 16-bit Operation Word into five smaller blocks, each 
of which has a fairly consistent meaning. 

Operation word instruction 


15 14 13 12 11 109 8 7 6 5 4 3 2 1 0 


tvoe 

dmod 

dreq 

smod 

sreg 


Instruction Word Parsing Analysis 


Type 


15| 14| 13 12| 


The types 0 to 15 instruction codes (16 classes) are allocated as follows: 
Type Instructions Range 


0 Bit manipulation. Move Peripheral and Immediate instructions 

1 Move byte Instructions 

2 Move longword instructions 

3 Move word instructions 

4 Miscellaneous instructions 

5 Add Quick, Subtract Quick, Set conditionally and Decrement instrs. 

6 Branch conditionally instructions 

7 Move Quick instructions 

8 OR, Divide and Subtract decimal instructions. 

9 Subtract, Subtract extended instructions. 

10 Unassigned 

11 Compare, Exclusive OR instructions 

12 AND, Multiply, Add decimal and Exchange instructions 

13 Add, Add extended instructions 

14 Shift and Rotate instructions 

15 Unassigned 
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MC 68000 Instruction Codes 


Dreg 


11 10 9 


Dreg has three main uses, normally holding the destination address in the 
general move instruction, one of the two register numbers for use in the specified 
instruction or embedded data for use in the add and subtract quick instructions. 

Dreg only refers to a register in those instances where the instruction has two 
register operands. 

Dmod 


8 7 6 


Dmod has two main uses, specifying the effective address mode of the 
destination operand in the general move instruction or, in most other cases it 
defines the size of the operation to be performed. 


Smod 


5 4 3 


Smod usually defines the effective address mode of the instruction, the 
source operand for the move instruction. 


Sreg 


2 10 


Sreg defines the effective address register, usually the source. 
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Instruction codes 

Bit Manipulation, Move Peripheral and Immediate 
Instructions - Type 0 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address 

Condition Codes 

Syntax 

11-9 

8-6 

5-3 

2-0 

Mode 

X 

N Z V C 

BCHG Dn,ea 

Dn 

5 


-ea- 

. dataltadd 

- 

- 

A - - 

BCHG data,ea 

4 

1 


-ea- 

dataltadd 

- 

- 

A - - 

BCLR Dn,ea 

Dn 

6 


-ea- 

dataltadd 

- 

- 

A - - 

BCLR data,ea 

4 

2 


-ea- 

dataltadd 

- 

- 

A - - 

BSET Dn,ea 

Dn 

7 


-ea- 

dataltadd 

- 

- 

A - - 

BSET data,ea 

4 

3 


-ea- 

dataltadd 

- 

- 

A - - 

BTST Dn,ea 

Dn 

4 


-ea- 

dataddmd2 - 

- 

A - - 

BTST data,ea 

4 

0 


-ea- 

dataddmd2 - 

- 

A - - 

MOVEP Dx,d(Ay) Dx 

1 1 X 

1 

Ay 

- 

- 

- 

- 

MOVEP d(Ay),Dx Dx 

1 Ox 

1 

Ay 

- 


- 

- - " 

ORI data,ea 

0 

0 s s 


-ea- 

dataltadd 

_ 

A 

A 0 0 

ORI data,CCR 

0 

0 

7 

4 

- 

A 

A 

AAA 

ORI data,SR 

0 

1 

7 

4 

- 

A 

A 

AAA 

ANDI data,ea 

1 

0 s s 


-ea- 

dataltadd 

- 

A 

A 0 0 

ANDI data,CCR 

1 

0 

7 

4 

- 

A 

A 

AAA 

ANDI data,SR 

1 

1 

7 

4 

- 

A 

A 

AAA 

SUBI data,ea 

2 

0 s s 


-ea- 

dataltadd 

A 

A 

AAA 

ADDI data,ea 

3 

0 s s 


-ea- 

dataltadd 

A 

A 

AAA 

EORI data,ea 

5 

0 s s 


-ea- 

dataltadd 

_ 

A 

A 0 0 

EORI data,CCR 

5 

0 

7 

4 

- 

A 

A 

AAA 

EORI data, SR 

5 

1 

7 

4 

- 

A 

A 

AAA 

CMPI data,ea 

6 

0 s s 


-ea- 

dataltadd 

- 

A 

AAA 
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Move byte instruction - Type 1 


Instruction 

Syntax 

Dreg Dmod 

11-9 8-6 

Smod 

5-3 

Sreg 

2-0 

Address 

Mode 

Condition Codes 
X N Z V C 

MOVE.B ea,ea 

source 

destination 

-ea- 

-ea- 


ALL * 
dataltadd 

- A A 0 0 


* Address register direct mode is not permitted 


Move longword instruction - Type 2 


Instruction 

Syntax 

Dreg Dmod 

11-9 8-6 

Smod Sreg 
5-3 2-0 

Address 

Mode 

Condition Codes 
X N Z V C 

MOVE.L ea,ea 




- A A 0 0 

source 


-ea- 

ALL 


destination 

-ea- 


dataltadd 



Move word instruction - Type 3 


Instruction 

Syntax 

Dreg Dmod 

11-9 8-6 

Smod Sreg 
5-3 2-0 

Address 

Mode 

Condition Codes 
X N Z V C 

MOVE.W ea,ea 




- A A 0 0 

source 


-ea- 

ALL 


destination 

-ea- 


dataltadd 



x Size s s Size 

Condition Codes 

0 = Word 0 0 = Byte 

u = Undefined 

1 = Longword 01= Word 

A = Affected 

10= Longword 

- = Unaffected 

. ea = Effective address 

0 = Cleared 

CCR = Condition code register 
. SR = Status register 

1 = Set 
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Miscellaneous instructions - Type 4 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address Condition Codes 

Syntax 

11-9 

8-6 

5-3 

2-0 

Mode X N Z V 

C 

NEGX ea 

0 

0 s s 


-ea- 

dataltadd A A 

A A 

A 

CLR ea 

1 

0 s s 


-ea- 

dataltadd - 0 

1 0 

0 

NEG ea 

2 

0 s s 


-ea- 

dataltadd A A 

A A 

A 

NOT ea 

3 

0 s s 


-ea- 

dataltadd - A 

A 0 

0 

MOVE SR,ea 

0 

3 


-ea- 

dataltadd 

- 

-- 

MOVE ea,CCR 

2 

3 


-ea- 

dataddmdl A A 

A A 

A 

MOVE ea,SR 

3 

3 


-ea- 

dataddmdl A A 

A A 

A 

SWAP Dn 

4 

1 

0 

Dn 

- A 

A 0 

0 

EXTW Dn 

4 

2 

0 

Dn 

- A 

A 0 

0 

EXT.L Dn 

4 

3 

0 

Dn 

- A 

A 0 

0 

NBCD.B ea 

4 

0 


-ea- 

dataltadd A u 

A u 

A 

PEA ea 

4 

1 


-ea- 

conaddmdl - - 

~ " 

- 

MOVEM list,ea 

4 

0 1 x 


-ea- 

conaltadd - - 

- 

- 

MOVEM ea,list 

6 

0 1 x 


-ea- 

conaddmd2 - - 

" - 


TST ea 

5 ' 

0 s s 


-ea- 

dataltadd - A 

A 0 

0 

TAS ea 

5 

3 


-ea- 

dataltadd - A 

A 0 

0 

ILLEGAL 

5 

3 

7 

• 4 

- - 

- - 

- 

TRAP data 

7 

1 

0 0 v v v v 

- - 

- - 

- 

LINK An,data 

7 

1 

2 

An 

- 

- - 

- 

UNLK An 

7 

1 

3 

An 

. . 

- - 

- 

MOVE An,USP 

7 

1 

4 

An 

. . 

- - 

- 

MOVE USP,An 

7 

1 

5 

An 

- - 

- - 

- 
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Miscellaneous instructions - Type 4 cont. 


Instruction 

Dreg 

Dmod 

Smod 

Sreg 

Address Condition Codes 

Syntax 

11-9 

8-6 

5-3 


2-0 

Mode X 

N Z 

V c 

RESET 

7 

1 

6 


0 

_ 

- 

_ 

_ 

NOP 

7 

1 

6 


1 

- 

- 

- 

- - 

STOP data 

7 

1 

6 


2 

A 

A 

A 

A A 

RTE 

7 

1 

6 


3 

A 

A 

A 

A A 

RTS 

7 

1 

6 


5 

- 

- 

- 

- - 

TRAPV 

7 

1 

6 


6 

- 

- 

- 

- - 

RTR 

7 

1 

6 


7 

A 

A 

A 

A A 

JSR ea 

7 

2 


-ea- 


conaddmdl - 

- 

- 

- - 

JMP ea 

7 

3 


-ea- 


conaddmdl - 

- 

- 

- - 

CHK.W ea,Dn 

Dn 

6 


-ea- 


dataddmdl - 

A 

u 

u u 

LEA.L ea,An 

An 

7 


-ea- 


conaddmdl - 

- 

- 

- - 


Add Quick, Subtract Quick, Set conditionally, Decrement 

instructions -Type 5 


Instruction 

Syntax 

Dreg 

11-9 

Dmod 

8-6 

Smod Sreg 
5-3 2-0 

Address Condition Codes 
Mode X N Z V C 

AddQ data,ea 
SUBQ data,ea 

data 

data 

0 s s 

1 s s 

-ea- 

-ea- 

altaddmod A A A A A 
altaddmod A A A A A 

See ea 

ccccll 

-ea- 

dataltadd 


DBcc Dn,data ccccll 1 Dn 


x Size s s Size 

Condition Codes 

0 = Word 0 0 = Byte 

u = Undefined 

1 = Longword 01= Word 

A = Affected 

10 = Longword 

- = Unaffected 

. ea = Effective address 

0 = Cleared 

CCR = Condition code register 

1 = Set 

. SR = Status register 


cccc = 4-bit Condition code 


vvvv = 4-bit Vector address 



H.7 







The Concise Atari ST Reference Guide 


Branch conditionally instruction - Type 6 


Instruction 

Syntax 

Dreg 

11-9 

Dmod Smod Sreg Address Condition Codes 

8-6 5-3 2-0 Mode X N Z V C 

Bcc data 

c c c c 

displacement (bits 0-7) 

BSR data 

0 

1 displacement (bits 0-7) 

BRA data 

0 

0 displacement (bits 0-7) 


Conditional tests for branch instructions 


cc 

Mnemonic 

Condition 

0 

T 

TRUE 

1 

F 

FALSE 

2 

HI 

HIGH 

3 

LS 

LOW or SAME 

4 

CC 

CARRY CLEAR 

5 

cs 

CARRY SET 

6 

NE 

NOT EQUAL 

7 

EQ 

EQUAL 

8 

VC 

OVERFLOW CLEAR 

9 

VS 

OVERFLOW SET 

10 

PL 

PLUS 

11 

MI 

MINUS 

12 

GE 

GREATER or EQUAL 

13 

LT 

LESS THAN 

14 

GT 

GREATER THAN 

15 

LE 

LESS or EQUAL 


There is no Branch TRUE BT or Branch FALSE BF, the codes are used by the 
BSR and BRA instructions 


. x Size 

s s Size 

Condition Codes 

. 0 = Word 

0 0 = Byte 

u = Undefined 

1 = Longword 

01= Word 

A = Affected 

10 = Longword 

- = Unaffected 

. ea = Effective address 

0 = Cleared 

CCR = Condition code register 

1 = Set 

. SR = Status register 



cccc = 4-bit Condition code 
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Move Quick instruction - Type 7 


Instruction Dreg Dmod Smod Sreg Address Condition Codes 

Syntax 11-9 8-6 5-3 2-0 Mode X N Z V C 

MOVEQ data,bn Dn 0 data "(bits 7-0) - A A 6 6 


2's complement data value 

Or, Divide, Subtract Decimal instructions - Type 8 


Instruction 

Syntax 

Dreg 

11-9 

Dmod 

8-6 

Smod Sreg 
5-3 2-0 

Address 

Mode 

Condition Codes 
X N Z V C 

OR ea,Dn 

Dn 

0 s s 


-ea- 

dataddmdl 

- 

A A 0 0 

OR Dn,ea 

Dn 

1 s s 


-ea- 

altmemadd 

- 

A A 0 0 

DIVU ea,Dn 

Dn 

3 


-ea- 

dataddmdl 

_ 

A A A 0 

DIVS ea,Dn 

Dn 

7 


-ea- 

dataddmdl 

- 

A A A 0 

SBCD Dy,Dx 

Dx 

4 

0 

Dy 

_ 

A 

u A u A 

SBCD -(Ay),-(Ax) Ax 

4 

1 

Ay 

- 

A 

u A u A 


Subtract, Subtract Extended instructions - Type 9 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address 

Condition Codes 

Syntax 

11-9 

8-6 

5-3 

2-0 

Mode 

X N Z V C 

SUBA.W ea,An 

An 

3 


-ea- 

ALL 


SUBA.L ea,An 

An 

7 


-ea- 

ALL 


SUB ea,Dn 

Dn 

0 s s 


-ea- 

ALL 

A A A A A 

SUB Dn,ea 

Dn 

1 s s 


-ea- 

altmemadd A A A A A 

SUBX Dy,Dx 

Dx 

1 s s 

0 

Dy 

_ 

A A A A A 

SUBX -(Ay),-(Ax) Ax 

1 s s 

1 

Ay 

- 

A A A A A 
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Emulation Instruction - Type 10 (#$A) 


Line-A 

Normally available for the implementation of user-written routines and 
entered by ensuring four MSB of the op word or defined word constant are 1010 
(10 dec), which will cause a trap to a user routine; other bits of op word may be 
used for parameter passing. The ST uses this instruction for initializing and 
operating the line-A functions on which GEM VDI and subsequently GEM AES 
are based - so use with care. 


Compare, Exclusive Or instructions - Type 11 (#$B) 


Instruction 

Syntax 

Dreg 

11-9 

Dmod 

8-6 

Smod 

5-3 

Sreg 

2-0 

Address 

Mode 

Condition Codes 
X N Z V C 

CMPA ea,An 

An 

xl 1 

-ea- 

ALL 

- A A A A 

CMP ea,Dn 

Dn 

0 s s 

-ea- 

ALL 

- A A A A 

CMPM -(Ay),-(Ax) Ax 

1 s s 

1 

Ay 

- 

- A A A A 

EOR Dn,ea 

Dn 

1 s s 

-ea- 

dataltadd 

- A A 0 0 


x Size s s Size 

Condition Codes 

0 = Word 0 0= Byte 

u = Undefined 

1 = Longword 01= Word 

A = Affected 

10= Longword 

- = Unaffected 

. ea = Effective address 

0 = Cleared 

CCR = Condition code register 
. SR = Status register 

1 = Set 
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MC 68000 Instruction Codes 


And, Multiply, Add Decimal, and Exchange instructions - 

Type 12 (#$C) 


Instruction 

Syntax 

Dreg 

11-9 

Dmod 

8-6 

Smod Sreg 
5-3 2-0 

Address 

Mode 

Condition Codes 
X N Z V C 

AND ea,Dn 

Dn 



-ea- 

dataddmdl 

- 

A A 0 

0 

AND Dn,ea 

Dn 



-ea- 

altmemadd 

- 

A A 0 

0 

MULU ea,Dn 

Dn 

3 


-ea- 

dataddmdl 

_ 

A A 0 

0 

MULS ea,Dn 

Dn 

7 


-ea- 

dataddmdl 

- 

A A 0 

0 

ABCD Dy,Dx 

Dx 

4 

0 

Dy 

_ 

A 

u A u 

A 

ABCD -(Ay),-(Ax) Ax 

4 

1 

Ay 

- 

A 

u A u 

A 

EXGD Dx,Dy 

Dx 

5 

0 

Dy 

_ 

. 

. . . 

_ 

EXGA Ax,Ay 

Ax 

5 

1 

Ay 

- 

- 

- 

- 

EXGM Dx,Ay 

Dx 

6 

1 

Ay 

- 

- 

- - - 

- 


Add, and Add Extended instructions - Type 13 (#$D) 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address 

Condition Codes 

Syntax 

11-9 

8-6 

5-3 

2-0 

Mode 

X N Z V C 

ADDA.W ea,An 

An 

3 


-ea- 

ALL 


ADDA.L ea,An 

An 

7 


-ea- 

ALL 


ADD ea,Dn 

Dn 

0 s s 


-ea- 

ALL 

A A AAA 

ADD Dn,ea 

Dn 

1 s s 


-ea- 

altmemadd A A A A A 

ADDX Dy,Dx 

Dx 

1 s s 

0 

Dy 

_ 

A A A A A 

ADDX -(Ay),-(Ax) Ax 

1 s s 

1 

Ay 

- 

A A A A A 
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Shift / Rotate instructions - Type 14 (#$E) 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address Condition Codes 

Syntax 

11-9 

8-6 

5-3 

2-0 

Mode X N Z V C 

ASL Dx,Dy 

Dx 

1 s s 

4 

Dy 

A A A A A 

ASL data,Dy 

count 

1 s s 

0 

Dy 

A A A A A 

ASL ea 

0 

7 


-ea- 

altmemadd A A A A A 

ASR Dx,Dy 

Dx 

0 s s 

4 

Dy 

A A A A A 

ASR data,Dy 

count 

0 s s 

0 

Dy 

A A A A A 

ASR ea 

0 

3 


-ea- 

altmemadd A A A A A 

LSL Dx,Dy 

Dx 

1 s s 

5 

Dy 

A A A 0 A 

LSL data,Dy 

count 

1 s s 

1 

Dy 

A A A 0 A 

LSL ea 

1 

7 


-ea- 

altmemadd A A A 0 A 

LSR Dx,Dy 

Dx 

0 s s 

5 

Dy 

A A A 0 A 

LSR data,Dy 

count 

0 s s 

1 

Dy 

A A A 0 A 

LSR ea 

1 

7 


-ea- 

altmemadd A A A 0 A 

ROL Dx,Dy 

Dx 

1 s s 

7 

Dy 

- A A 0 A 

ROL data,Dy 

count 

1 s s 

3 

Dy 

- A A 0 A 

ROL ea 

3 

7 


-ea- 

altmemadd - A A 0 A 

ROR Dx,Dy 

Dx 

0 s s 

7 

Dy 

- A A 0 A 

ROR data,Dy 

count 

0 s s 

3 

Dy 

- A A 0 A 

ROR ea 

3 

3 


-ea- 

altmemadd - A A 0 A 

ROXL Dx,Dy 

Dx 

1 s s 

6 

Dy 

A A A 0 A 

ROXL data,Dy 

count 

1 s s 

2 

Dy 

A A A 0 A 

ROXL ea 

2 

7 


-ea- 

altmemadd A A A 0 A 

ROXR Dx,Dy 

Dx 

1 s s 

6 

Dy 

A A A 0 A 

ROXR data,Dy 

count 

1 s s 

2 

Dy 

A A A 0 A 

ROXR ea 

2 

7 


-ea- 

altmemadd A A A 0 A 
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Emulation instruction - Type 15 (#$F) 


Line-F 

Normally available for the implementation of user-written routines, and 
entered by ensuring four MSB of the op word or defined word constant are 1111 
(15 dec), directing the trap service to a user routine. Other bits of op word may be 
used for parameter passing. 

This service trap is used by the MC68020 processor for passing co-processor 
instructions. The ST uses it in processing the application environment services 
(AES), so be careful. 


x Size s s Size 

Condition Codes 

0 = Word 0 0 = Byte 

u = Undefined 

1 = Longword 01= Word 

A = Affected 

10 = Longword 

- = Unaffected 

. ea = Effective address 

0 = Cleared 

CCR = Condition code register 
. SR = Status register 

1 = Set 
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Address modes 


Encoding 

The range of addressing modes are coded consistently throughout the 
MC68000 instruction set and may be summarized as follows: 


Addressing mode 

Syntax 

Mode 

# 

Register 

# 

Extension 

words 

Data register direct 

Dn 

0 

n 

0 

Address register direct 

An 

1 

n 

0 

Address register indirect 

(An) 

2 

n 

0 

Address register indirect 
with postincrement 

(An)+ 

3 

n 

0 

Address register indirect 
with predecrement 

-(An) 

4 

n 

0 

Address register indirect 
with displacement 

d(An) 

5 

n 

1 

Address register indirect 
with index 

d(An.Ri) 6 

n 

1 

Absolute short ABS.S 

$xxxx 

7 

0 

1 

Absolute long ABS.L 

Sxxxxxx 7 

1 

2 

Program counter with 
displacement 

d(PC) 

7 

2 

1 

Program counter with index 

d(PC.Ri) 7 

3 

1 

Immediate Imm 

#$xxx 

7 

4 

lor2 


n = Register number 0 to 7 

Extension Word = Number of extension words following the op word due to this 
address mode (source and destination ext. words are cumulative) 

Mode # — Dmod and Smod in instruction code tables 

Register # ==Dreg and Sreg in instruction code tables 
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Appendix I 
Error codes 

1.2 

1.3 

1.4 


BIOS error codes 
GEMDOS error codes 
Miscellaneous error codes 


1.1 
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BIOS error codes 


Error 

code 

Function 

Comments 

0 

-1 

-2 

O'K 

Error 

Drive not ready 

Successful operation 

Not ready, not attached or busy 

-3 

-4 

-5 

Unknown command 
CRC error 
Bad request 

Command not understood by device 
Soft error while reading sector 
Bad parameter. Cannot do request 

-6 

-7 

-8 

Seek error 
Unknown media 
Sector not found 

Drive could not seek 

Foriegn media. Bad zero boot sector 

-9 

-10 

-11 

No paper 
Write fault 
Read fault 


-12 

-13 

-14 

General error 
Write protect 
Media change 

Reserved 

Read only or protected media 
Media changed since last write or 
the rd/wr op not done (file error) 

-15 

-16 

-17 

Unknown device 
Bad sectors 
Insert disk 

BIOS doesn't recognize device 
Format yielded bad sectors 
Disk not in drive (shell error) 
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GEMDOS error codes 


Error PC DOS 

Function 


code equivalent 

Supported 

Not supported 

-32 

1 

Invalid function number 


-33 

2 

File not found 


-34 

3 

Path not found 


-35 

4 

No handles left 




(too many open files) 


-36 

5 

Access denied 


-37 

6 


Invalid handle 

-38 

7 



-39 

8 

Insufficient memory 


-40 

9 


Invalid memory block add 

-41 

10 

** Insufficient memory 


-42 

11 

** Insufficient memory 


-43 

12 




13 



-45 

14 



-46 

15 

Invalid drive specified 


-47 

16 

** Invalid operation 


-48 

17 



-49 

18 

No more files 



The 

running 


list of PC-DOS equivalent error codes supported may be found by 
the GEM demonstration program (Appendix L). 
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Miscellaneous error codes 


Error 

Function 

code 


-64 

Range error 

-65 

Internal error 

-66 

Invalid program load format 

-67 

Setblock failure due to growth restrictions 
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Appendix J 


BASIC GEM 


GEMSYS J.2 

VDISYS J.2 

SYSTAB J.3 

BASIC example J.4 

BASIC assembler J.6 

Hand coding J.7 

Coding chart J.10 
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ST BASIC provides the programmer with direct access to parts of the 
operating system AES and VDI interface. 


GEMSYS 


The AES control arrays are accessed through the AES parameter block (GB 
pointer), the block provides pointers to the other supplementary AES parameter 
blocks: 


control table +$0 \ 

global array +$4 I 

int_in table +$8 I 

int_out table +$C I 

addr_in table +$10 I 

addr_out table +$14 / 


Data input and output 
as specified in the AES 
traps and utility tables. 
Chapter 5 


The tables are used by the programmer to input data, call the appropriate 
GEM AES function, GEMSYS(n), and read any reply from the data placed in the 
output tables by the function. 


VDISYS 

The VDI parameter blocks are directly accessible from BASIC: 

contrl input \ 

ptsin input I 

ptsout output I tables 

intin input I 

intout output / 

The appropriate tables are loaded with data and the function called via 
VDISYS(l), the (1) being a dummy argument. Any reply is read from the output 
tables. 


GEMSYS 

| 


VDISYS 

1 

V 


i 

V 

GB — > control 

\ 

contrl 

global 

1 

intin 

int_in 

1 Indirect 

intout 

int_out 

1 access 

ptsin 

addr_in 

1 

ptsout 

addr_out 

/ 
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SYSTAB 


ST BASIC also provides access to a BASIC system table of the following read 
only pointers and parameters: 


Graphics resolution 


Editor ghost line style 
(Read/write) 


Edit AES handle 
List AES handle 
Output AES handle 
Command AES handle 
Edit open flag 
List open flag 
Output open flag 
Command open flag 
Graphics buffer 
GEM flag 


+$0 l=high resolution 

2=medium resolution 
4=low resolution 
+$2 0=thickened 
1 intensity 
2=skewed 
3=underlined 
4=outline 
5=shadow 
+$4 1 \ 

+$6 2 I default 

+$8 3 I 

+$A 4 / 

+$C \ 

+$E I 0=closed 

+$10 I l=open 

+$12 / 

+$14 Longword 32K buffer pointer 
+$18 0_normal, l_off 


The GEM flag is used to turn BASIC I/O off and increase the processing 
speed of GEM based operations. With BASIC partially off, the I/O functions 
involving the screen, mouse and keyboard are disabled, although disk I/O is still 
enabled. 

The BASIC functions can be re-enabled after the burst of speed for user input 

Not all GEM and VDI functions are available through BASIC, some of the 
BASIC housekeeping activities negate the effect of the functions. 
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Cautionary notes: 

Ensure that evaluations of the graphic primitives take into account color. 
Many experiments may appear not to work simply because the writing color is 
the same as the screen backgound. 

Characters are written to the screen starting from the left-hand edge and will 
probably be obscured by the command screen border unless the programmer 
moves it out of the way. 


BASIC example 


Use the mouse and the right button to draw a primitive, use the left button to 
change the primitive. Note the effect on a primitive of crossing the left hand 
screen edge. 


10 start: CLEAR: a#=gb:int_out=PEEK(a#+12) 

20 FULLW 2:CLEARW 2 

30 INPUT "GDP (1 to 9) ";gdp 

40 IF gdp or gdp9 THEN GOTO start 

50 POKE systab+24,1: REM BASIC I/O off 

60 POKE contrl,122:POKE contrl+2,0:POKE contrl+6,1 
70 GOSUB curson 

80 attribs: GEMSYS(79) 

90 x=PEEK(int_out+2) : REM x mouse 

100 y=PEEK(int_out+4) : REM y mouse 

110 key=PEEK(int_out+6) : REM button state nil_left_right 

120 ON key+1 GOSUB showcurs, done, drawprim 

130 GOTO attribs 

140 done: POKE systab+24,0:GOTO start: REM nasty return 

150 drawprim: REM 

160 COLOR 1,(RND*15)+1,1,RND*25,2 : REM random color 

170 IF mouse=0 THEN GOTO 210 

180 mouse^O 

190 POKE contrl,123:POKE contrl+2,0:POKE contrl+6,0 
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200 VDISYS(l) : REM hide cursor 

210 POKE contrl,ll:in=0:xop=x+50:yop=y+50:rc=0 
220 ptin=2:IF gdp=4 THEN ptin=3:xop=0:yop=0:rc=50 
230 IF gdp=2 OR gdp=3 THEN ptin=4:xop=0:yop=0:in=2 
240 POKE contrl+2,ptin 

250 IF gdp=6 OR gdp=7 THEN xop=50:yop=20:in=2 

260 IF gdp=5 THEN xop=60:yop=40 

270 IF inO THEN POKE contrl+6,in 

280 POKE contrl+10,gdp 

290 POKE ptsin,x 

300 POKE ptsin+2,y 

310 POKE ptsin+4,xop 

320 POKE ptsin+6,yop 

330 REM IF ptin=2 THEN GOTO nxtin 

340 POKE ptsin+8,rc 

350 POKE ptsin+10,0 

360 REM IF ptin=3 THEN GOTO nxtin 

370 POKE ptsin+12,50 

380 POKE ptsin+14,0 

390 REM nxtin: IF in=0 THEN GOTO draw 

400 POKE intin,(rnd*3600) 

410 POKE intin+2,(rnd*3600) 

420 draw: VDISYS(l) 

430 RETURN 

440 showcurs: IF mouse=l THEN RETURN 

450 POKE contrl / 122:POKE contrl+2,0:POKE contrl+6,0 

460 curson: POKE intin, 0: VDISYS(l) 

470 mouse=l: RETURN 


Look at the spelling of the variables, particularly contrl, if the program 
crashes. Although BASIC access to the processor is normally in user mode, PEEK 
and POKE instructions are performed in supervisor mode to provide access to all 
parts of memory. 
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BASIC ASSEMBLER 

There are many ways of producing a combined BASIC /assembler program 
on the Atari ST computer, the following demonstrates one of them: 

First create the assembler subroutine of relocatable 68000 machine code that 
can be saved using a BASIC program similar to the following. 


10 RESTORE 

20 ZA$="12345678901234567890": 

30 ZB$=STRING$(100,"*"): 

40 y=VARPTR(ZA$): 

50 DEF SEG=y: 

60 FOR a=0 TO n 
70 READ x:POKE a,x: 

80 NEXT a 

90 BSAVE "progl.asm",y,n: 

100 STOP 
200 DATA 


REM \Use either method to 
REM /create space for code 
REM Somewhere to put code 
REM Set up loop offset 

REM Put code into memory 

REM Save code to disk 

REM Byte sized data 


The machine code will probably be loaded into a space created within the 
main BASIC program by a dummy variable. Obviously, any number of different 
machine code utilities can be loaded into the same space dependant upon 
program state, or they may be stored in individual program spaces. 

Parameters are passed to the machine code routine on the user stack which 
contains an integer count of the number of parameters passed on top. The next 
item on the stack is a longword pointer to the 8-byte per parameter array. String 
variables use the array parameter as a pointer to the string. 
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Output can be placed in predefined variables and if correctly formatted, read 
back by the BASIC program. 


10 ZB$=STRING$(1 00,"*") : 

20 ZR$="1 2345678": 

30 y= V ARPTR(ZB$) : 

40 ans= VARPTR(ZR$) : 

50 BLOAD "progl.asm",y: 


REM Space to load code 
REM Space for reply 
REM Position for code 
REM Position of reply 
REM Load code from disk 


100 CALL progl(x,y,ans): REM Call program code, passing parameters 

REM x and y, returning data in the 
REM variable ans 


An alternative might be to compile the code within the BASIC program 
proper if the machine code program length is quite short. 


Hand coding 

Many programmers had their first contact with assembly language 
programming through hand coded 8-bit microprocessor routines embedded in 
short BASIC programs. MC68000 code is slightly more complicated to assemble 
than 8-bit code, but is still perfectly manageable. 

Use tables of instruction types 0 to 15 (Appendix H), to generate the basic 
code i.e: 

4096 * type + 512 * dreg + 64 * dmod + 8 * smod + sreg 

and the address mode encoding table (Pg H.14) to determine the effective 
address (-ea-) values if required. 
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Example of a hand coded program 


Project: MONITOR SCREEN INVERSION Author: 

Version #: 2 Date: DEC/85 


Label 

Syntax 

Src 

Mnm 

Dest 

Mnm 

type 

dmc 

dreg 

3d |sreg 
smod 

Dec 

value 

Notes 


MOVE.W 

N 

-(SP 

3 

7 

4 

7 

4 

16188 

GET OLD COLOUR 

2 



-1 






-1 


4 

MOVE.W 

N 

-(SP 

3 

7 

4 

7 

4 

16188 

SETCOLOR (Pg 3. 

6 



0 






0 


8 

MOVE.W 

N 

-(SP 

3 

7 

4 

7 

4 

161 8f^ 


TO 



7 






7 


2 

TRAP 

14 


4 

7 

1 


14 

20048 


4 

ADDA.W 

N 

SP 

13 

7 

3 

7 

4 

5708^ 

TIDY STACK 

6 



6 






6 


8 

EORI.W 

N 

DO 

0 

5 

1 

0 

0 

2624 

TOGGLE COLOUR Bl 

20 



1 






1 


2 

MOVE.W 

DO 

-(SP 

3 

7 

4 

0 

0 

16128 

SET NEW COLOUR 

4 

MOVE.W 

N 

-(SP 

3 

7 

4 

7 

4 

16188 


6 



0 






0 


8 

MOVE.W 

N 

-(SP 

3 

7 

4 

7 

4 

16188 


30"~ 



7 






7 


2 

TRAP 

14 

SP 

4 

7 

1 


14 

20048 

) 

4 

ADDA.W 

N 

6 

13 

7 

3 

7 

4 

5708' 

1 TIDY STACK 

6 









6 


8 

RTS 



4 

7 

1 

6 

5 

20085 

i RETURN TO BASIC 
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Use this type of program to load the code into a file on disk: 

10 restore:n=70 
20 zb$=string$(100,"*") 

30 y=varptr(zb$) 

40 def seg = y 
50 for a=0 to n step 2 

60 read x:poke a,int(x/256):poke a+l,x mod 256 

70 next a 

80 bsave "b/w.asm" / y / n+2 
100 stop 

210 data 16188,-1,16188,0,16188,7 
220 data 20046,57084,6,2624,1 
230 data 16128,16188,0,16188,7 
240 data 20046,57084,6 
250 data 20085 
300 data 0,0,0,0,0,0,0,0,0,0,0,0,0 
310 data 0,0,0,0,0,0,0,0,0,0,0,0,0 
320 data 0,0,0,0,0,0,0,0,0,0,0,0,0 

and to toggle the screen or border color, run the following BASIC program 
which loads the file back from disk and executes it: 


10 zb$=string$(100,' "*") 

20 y=varptr(zb$) 

30 bload "xb/w.asm",y 
40 call y 
50 stop 

The following brief notes may be useful in compiling programs in the above 
manner: 


Entry to machine code level from BASIC is in supervisor mode. 

If you drop to user mode, be careful where you place your stack. Perhaps you 
might like to use the following sequence of instructions that jump over your stack 
or data to the beginning of the executable code. DATA 17402,4,24576+dis,... 


Start 


LEA4(PC)AI 
BfTAdis 
"Text or " 
stack 
Program 
code 


Set A1 to start of text 

dis = 2 + text length (must be even) 


Start of program 


If in difficulties with a BRApch or JuMP, surround with NOP's to make the 
jump less sensitive to the count. 
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Program development tools 


Atari MC68000 assemblers K.2 

Seka K.2 

Hisoft K.4 

GST K.5 

Metacomco K.6 

Digital Research K.7 

Compatibility table K.8 

General assembler compatibility K.9 

Assembler directives compatibility K.10 

Assembler conversions K.ll 

General conversion chart K.12 

Basic calling procedure K. 1 4 

Executable file size K.15 

C compilers K.16 
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Atari MC 68000 assemblers 

There are a number of assemblers available for the Atari ST programmer, 
they have small discrepancies in the assembly syntax used, no uniformity in the 
library and utility files supplied or of the method of creating an executable 
program. 

This makes it difficult for the inexperienced programmer to type as source a 
program listing created for another assembler, and to get it operational. What I 
have tried to produce is an analysis of each assembler and a conversion chart that 
may help in isolating fairly straightforward problems. 

Where a published program uses a particular assembler specific facility 
(special macros etc.) then translation will not always be possible by simple 
substitution and there may be no easy solution. Hopefully the general assembler 
compatibility chart will indicate whether there is the likelyhood of a conversion. 

This guide is very much less than perfect, but it is an attempt at assisting 
inexperienced programmers in a very difficult field. 

The assemblers 

Very few of the assemblers provide programming details of the Motorola 
M68000 processor instruction set, or teach the user basic assembler language 
programming. If the reader has not written assembly language programs before, 
the brief overview of the language in Appendices G and H should help. 

Seka 

The combined editor/assembler/monitor/debugger is held in a very 
compact 20K of code, this means that parts of the package are a bit weak. 
Although two editors are supplied, a line editor and a screen editor, neither 
performs block find and replace function. Use the Atari wordprocessor in non wp 
mode for major or block changes in large files. What is likely to be more of a 
significant problem is the limitation to a leading letter for label and symbol 
names (the use of an underscore is very common in most libraries and the Atari 
system variables). A possible solution would be to substitute a little used letter 
for the leading underscore, say 'z'. 
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On the positive side, the Seka assembler generates absolute or relocatable 
executable code directly, has limited macro and conditional capability, and is a 
quick assembler for writing programs if you know what you are doing - some of 
the runtime error messages are incomprehensible with no guide in the manual as 
to what they are trying to tell you. It is very convenient having all the facilties in 
one program, an assembly error leaves the editor at the erroneous line for 
immediate correction and reassembly or the programmer may trace through the 
code with the monitor/debugger. The editor also allows the programmer to type 
the source code in free format; the assembled output listing is automatically 
tabulated, but there is no way of simply listing the code to a printer in a tabulated 
form which makes the source difficult to read when trying to debug program 
logic errors. Source files entered in a tabulated form are occasionally detabulated 
in parts of the assembly list file. The system for linking files is a bit messy and 
very non-standard as are some of the assembler directives. The 
monitor/debugger allows the programmer to single /multiple step through a 
program, examine registers, set breakpoints and provides all the necessary 
facilities to aid program debugging. It is important to ensure that program files 
are of even length; odd file lengths sometimes produce run-time errors not 
discovered by the debugger, which makes the fault extremely difficult to locate. 
The assembly syntax is pretty standard; labels must terminate in a colon, 'movea' 
should be entered as 'move', the assembler correcting the syntax but strangely 
'adda' is acceptable. 

The 36 page manual limits the two examples to very simple TOS programs, 
one of which includes macros. The manual has a lot of ground to cover which it 
manages only at a fairly minimal level, i.e it does not provide enough information 
regarding the cause of errors - an error in a macro is flagged as an illegal operand 
in the calling code. The manual contains a very useful single page command 
summary. 

The package is very easy to use, although not as powerful as some of the 
other packages in this appendix. As an assembler, it is complete with minimal 
libraries of DOS calls equates and GEM array generators. 
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Hisoft 

A combined editor/ assembler with a seperate monitor/debugger. The Hisoft 
assembler employs include files to ease the access to the GEM and TOS functions 
and produces machine code directly. The include files require function 
parameters to be explicitly placed in the parameter arrays as per the assembler 
GEM example (Appendix L). The assembler does not have a linker facility, which 
makes that aspect a little unusual, and does not like labels followed only by 
comments on the same line. The editor is a full feature program with the minor 
omission of displaying and handling only one file at a time. 

The package contains include files of equates for BDOS, BIOS, extended BIOS 
calls, system variables and a GEM include file that provides program 
initialisation, VDI and AES constant equates and parameter array initialisation. 
The package does not provide details of the data (Chapters 3, 4 and 5) to be 
placed in the arrays. 

The monitor/debugger besides supporting the usual step, set breakpoints, 
examine and modify registers and memory etc. enables the assembled program 
to be run and debugged using seperate screens for the graphics and the monitor 
output, a very useful feature. 

The documentation is well written and provides a good introduction for the 
beginner. 

A very friendly package that could benefit from the use of a RAM disk to 
hold all the files in memory at once. In a 51 2K machine, seperating the program 
into two components does not appear to provide the optimum 'modus operandi'. 
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GST 

The GST assembler package has a very good GEM based editor that enables 
up to four files to be worked on at the same time in multiple windows, copying 
blocks from one to another with ease. The only possible complaint regarding the 
editor could be the relatively slow loading of program and files and of cursor 
movement up and down within the file. 

The assembler can produce relocatable binary output suitable for the linker 
or executable code directly from position independant source. The executable 
code does not contain the standard Atari TOS file header preamble, which must 
be added by the programmer if the file is to act as a stand alone program. A very 
useful list of the instruction mnemonics is provided, as is information on the 
optimisation route taken in compiling code. The use of an underscore for the 
leading character of a label or symbol is not permitted, which entails a degree of 
non compatibilty with the standard Atari ST notation for some system variables 
and extended BIOS calls. 

The assembly of source is slow by virtue of the many disc accesses, but the 
use of RAM disc for compilation and the loading of all modules into memory 
together will obtain reasonable speed. There is no uninitialised data (BSS) 
directive which means that GEM program files held on disc are about IK larger 
than necessary. If some instruction sizes are not explicitly stated, a liberal supply 
of warning messages are issued. 

The GST linker is also supplied with the Metacomco macro assembler, it 
enables other high level language modules written in Pascal, Assembler and C to 
be linked together in a single program. 

The library supplied contains macro definitions of conditional structures. 
GEM and TOS libraries are not supplied. 

The documentation consists of seperate index-less assembler, editor and 
linker manuals, which are very well packaged in a ring binder, the manuals are 
very detailed, but may be difficult for the inexperienced assembly language 
programmer to read. 
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Metacomco 

The screen editor is good but does not follow the normal GEM style of access, 
although the user will very quickly adjust. The global 'find and replace' is 
comparitively slow as the screen is re-written for each change. 

The assembler is slow in comparison with the smaller assemblers evaluated 
in this appendix and would benefit greatly from the use of RAM disk. Symbols 
may be of up to thirty significant characters, but tabulated 'dc' data values on one 
source line seperated by a comma and space are not permitted - the space may be 
used to introduce a comment. 

Metacomco supply the GST linker with their macro assembler which can 
produce either a binary file suitable for the GST linker or a CP/M 68K object file 
suitable for the DR link68 linker; which links to the complete DR set of GEM and 
TOS libraries, but is undocumented. 

The Metacomco assembler package is supplied with assembler source to the 
GEM libraries and a monitor program. The monitor provides breakpoints, a trace 
mode and register/memory change and examine facilities. 

The assembler suite of programs can be batched using the Menu+ program 
provided. It enables the sequence of edit, assemble, link and run to be controlled 
by the menu file, which runs and loads each program producing the specified 
outputs as requested and entering the next stage automatically via a pause, wait 
or continue programmed instruction. 

The documentation is concise and very well laid out, but gives no additional 
explanation on assembly errors to that displayed on the screen during the 
assembly phase. 
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Digital Research 

The Digital Research package can use any editor/ word processor that is 
capable of producing an unformatted ASCII text file. 

The assembler, which is a reasonable implementation of the Motorola 
M68000 assembly language, has no macro facilities but optimises instructions and 
branches to produce efficient code. 

The DR LINK68 linker provides access to the DR GEM and TOS libraries that 
consist of accessory and application header files, GEMDOS, BIOS, XBIOS, VDI, 
AES and floating point libraries. 

Although the assembler, linker and relocator programs can be installed as 
TTP (TOS Takes Parameters) files, the programs are much easier to run via the 
Activenture Corp. batch program. The additional use of a RAM disk to hold the 
files and programs produces a very reasonable response, eliminating much of the 
disc access. 

The development package was intended for software developers and not the 
general public, as such it is written with a high degree of technical jargon. 
Gomplete with no omissions, a veritable 'War and Peace' It provides information 
on all of the GEM VDI functions and makes no mention of those not 
implemented on the ST. 

DR C language modules may also be linked with the assembled source and 
DR libraries to produce executable programs. 

The package is supplied with the DR symbolic interactive debugger 'SID' 
enabling the program writer to test and debug M68000 executable code, either 
from TOS or GEM, read/write/move blocks of memory, disassemble code or 
produce a hex dump, examine the CPU state, trace, run or step through the code. 

Atari have recently made available a new faster linker ALN to software 
developers, which replaces both LINK 68 and RELMOD, the linker and relocation 
package respectively. 
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Compatibility table 

The analysis of each package necessarily concentrates on the flaws, looking 
for inconsistences and omissions. What may not be apparent is how good in 
absolute terms the packages are, any purchaser being able to justify the cost on 
technical excellence alone. 

It may be useful to give an indication as to the range of likely purchaser of 
each package: 

K_seka assembler: 

Absolute beginner - competent programmer: Very fast program development 

Hisoft devpak: 

Absolute beginner - competent programmer: Fast program development, 
with GEM and TOS bindings. 

GST macro assembler: 

Absolute beginner - expert: Full feature assembler capable of linking with 
other high level language modules to form executable programs. 

Metacomco assembler: 

Competent programmer - expert: Full feature assembler with macros. DR's 
linker may be used to provide access to the complete set of system libraries, and 
GST's linker to link high level language modules into a combined language 
program. 

Digital Research assembler: 

Software developer: Not available to the general public. 
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General assembler compatibility: 


Not exhaustive, merely a guide to what facilities are available. 


Function 

Hisoft 

assembler 

S — 

Digital 

Research 

GST 

assembler 

Metacomco 

assembler 

Kseka 

assembler 

Editor 

GENST 

- 

Edit 

Ed j 

dl-in-one package 

multifile edit 

No 

Can use an 

r Yes (4) 

No 

No 

screen/line 

screen 

wordproce: 

;sr screen 

screen 

Line & screen 

GEM 

Yes 

ASCII text. 

Yes 

No 

No 

Assembler(i/p) 

(•S) 

AS68 (.S) 

(.ASM) 

(.ASM) 

(.S) 

Output 

-nolink 

Executable 
or binary 

Binary file 

Binary file 
or executal 
(no file hea 

See linker 1 
le 

der) 

ixecutable 

Optimiser 

Yes 

Yes 

Yes 

Yes 


Macros 

Yes 

No 

Yes 

Yes 

Yes 

conditional 

Yes 

Yes 

Yes 

Yes 

Yes 

Linker 

Input 

LINKST 

Link68 

GST-LINK 
Binary file 

Can use eithe 
GST-LINK or 

r Relocatable 
mode 

Submissions 

Output 

Libraries 


Batch file 

Control file 
File-headei 
reloc table 
code 
data 

opt sym tal 

DR's LINK6! 
& RELMOD 
urograms 
(GST-LINK 
is supplied) 
>le 

only 

(odd format) 

GEM ^ 

fes-limited 

Yes-comple 

te No 

Yes-source 

Kes-minimal 

TOS ' 

( es-limited 

Yes-comple 

te No 

No 

i'es-minimal 

Maths 

No 

Yes 

No 

No 

No 

Monitor 

MONST 


No 

Yes 

Yes 

Debugger 

Yes 

SID 

symbolic 

interactive 

debugger 

Not suppli 
Linker can 
debug sym 
in program 

:d Supplied 
put as source 
b example 
on disk 

Yes 

Relocator progra 

m No 

RELMOD 

No 


No 

Symbols 

16 signif 


8 signif cha 

r Upto 30 cha 

r 

Label) column 1 

Space 

Space or : 

Space or : 

Space or : 

Colon 

end ) column n 
Directives 

Space or : 

Colon 
Optional pe 

Colon 

iriod 

Colon 

Colon 

Comment) col 1 

* 

* 

* or ; 

* or ; 

* or ; 

) col n 

space 

* 

; or space 

; or space 

; 

Case (Symbols) 

Selectable 

Significant 

Not signife 

:nt Selectable 

Not significant 

Quotes 

Sngle/dble 

Sngle/dble 

Single 

Single/doubl 

e Single/double 

GST assembler executable code must supply a TOS program header and be 

written in positition-independant code before it can be run. The default file 
extensions are given in brackets. 
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Assembler directives compatibility 


Directive 

Explanation 

Hisoft 

Digital 

Research 

GST 

Metacomco 

Kseka 

Include(i/f 

') Insert external 

Yes (.S) 

No 

Yes (.IN) 

Yes 

Abs. code 


file 



(.MAC) 


via linke 

Text 

Relocatable code 

No 

Yes 

Section cod 

e Yes (def) 

lode == 

Data 

Initialised data 

No 

Yes 


Yes 

No 

BSS 

Uninitialised dat 

i DSBSS== 

Yes 

No 

Yes 

Data == 

even 

Align to word 

Yes *** 

Yes 

*** 

*** 

Yes & oc 

ORG odd 

> Absolute sectic 

n Yes 

Yes 

Yes 

No 

Yes 

Common 

Common region 

No 

Yes 

Yes 

No 

No 

RORG <ad 

lr> Adjust curr lc 

icn No 


Yes 

Yes 

No 

Offset 

Define table via 

No 

Yes 

Yes 

Yes 

No 


a DS directive 






"OFT - 

Select addr mode 

Diff meani 

ng Ignored 

PC or Ab 

s No 

“TJo - 

Globl 

External label 

Yes 

Yes 

No 

No 

Yes 

Xref 

External name 

Yes 

Yes 

Yes 

Yes 

No 

Xdef 

Internal label 

Yes 

Yes 

Yes 

Yes 

No 


for external use 






Module 

Link module nan 

le Yes 


Yes 



Comment 

Include commen 

s 


Yes 




in linker listing 






Equ 

Symbol 

Yes 

Yes 

Yes 

Yes 

Yes & = 

Equr 

Register 

Yes 



Yes 


Reg 

Register list 


Yes 

Yes 

Yes 


Set 

Temporary value 

Yes 

Uses Equ 


Yes 


DC 

Constant 

Yes 

Yes 

Yes 

Yes 

Yes 

DS 

Storage 

Yes 

Yes 

Yes 

Yes 


DCB 

Constant block 



Yes 

Yes 

Blk == 

RS 


Yes 




No 

Conditiona 

Is 

Yes 

Yes 

Yes 

Yes 

Yes 

IF eq,ne,gt 


Yes 

Yes 

No 

Yes 

If, Else 

ge,lt,le 






IFB 

String c,nc 


Yes 

Yes 

Yes 

Yes 

No 

Symbol d,r 

d 

Yes 


Yes 

Yes 

No 

Library Sys 

G! 

M/TOS GE 

M/TOS/FI 

’ None 

None 

Minimal 

Macro 




If,Else,For 







While/Unti 







Repeat,Cas 

3 



Sub nth arg 

\n 

Not 

[W~ 

Xh 

“7n 


Sub unique # nm 

\@ 

applicab 

e [-L] 

\@ 

?o 

Mask2 



Ignored 


Ignored 





Ignored 


Ignored 



*** DS and DC word and longwords automatically align to boundaries 
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Assembler conversions 

There are a number of assemblers available for the ST, each with different 
characteristics, this section is provided as an aid to translation of programs 
presented from alternative sources. 

One of the by-products of the compatibility information is that it provides the 
opportunity of generating a subset of directives and instructions that are of 4 
almostO universal applicability, but compatibility does tend to look at the lowest 
common denominator. 

All of these programs have other attributes which provide a significant 
improvement in performance over the base standard, these improvements are not 
always apparent to the casual user but very handy to have if required. 

If you wish to write source for maximum compatibility with other 
assemblers, the following should minimise the problems: 

- Size all instructions (move, clr, lea etc. do not default) 

- Size branches (avoids masses of GST warning messages) 

- Avoid using reserved words for labels such as text, code etc. 

- Use a semicolon for all comments (except Hisoft and DR which should use a 

- Do not tabulate DC data, added spaces do not travel well. 

- Limit label and symbol lengths to eight characters. 

- Use 'EQU' directive, not '='. 

- After text and data sections, it is wise to ensure that the PC is on a word 
boundary. Most programs use 'EVEN', some assemblers use 'DC' and 'DS' with a 
.W or a .L extension. 

Sizing instructions is perhaps the most difficult factor to come to terms with. 
I find it extremely difficult to ignore and not stop and read any warning 
messages, and become a little irritated to find that a branch 'might be short' or 
that LEA has not got a .L extension. All warnings should be significant or else 
they will 1 allO be treated as superfluous information. 
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General conversion chart 


FROM 


To-Kseka 


Hisoft 


GST 


Metacomcffi DR 


Comments 


Macros 

Kseka 

comment 

Opcodes 


MACRO 

?1 

?2 

?o 


blk 


\1 

\2 

\@ 


Macros 

Hisoft 

comment 

Opcodes 


?1 

?2 

?o 


blk 


ds 

MACRO 

\1 

\2 

\@ 


MACROAj 

[A] 

[B] 

[.L] 

Size Opcocji 
& branch 
ds 


\1 

\2 

\@ 

es Size 

opcodes 

ds 


n.a. 
Expand| 
code 
in full 


Program may use| 
many labels that 
hot appear to have 
any function. They 
ill probably be 
breakpoints. 


do 


ds 


ds : 

MACRO 

\1 

\2 


MACRO A1 

[A] 

[B] 

[•L] 

Size Opcocji 
& branch 


n.a. 
Expand| 
code 
in full 


Places GEM data 


es Size 
opcodes 


directly into VDI 
and AES arrays. If 
the source includes 
3EM calls, follow 
:he example 
n appendix L 


Macros 

GST 

comment 

Opcodes 


MACRO 

?1 

?2 

?o 


blk 


MACRO 

[A] 

[B] 

[-L] 


ds 


A 


Macros 

?1 

Metacomco ?2 
?o 

comment 
Opcodes 


MACRO 

\1 

\2 


MACRO 

\l 

\2 

\@ 


ds 


n.a. Seems to like all 
Expand instructions sized) 
code ar issues lots of 
in full v earning messages. 

I .ibrary of conditio 
rial macros will 
cause problems. 

( lode has to belong] 
:o a section. 


MACKU Af 

[A] 

[B] 

[•L] 


Size 

branch 


Digital 

Research 

comment 

Opcodes 


blk 

code 

data 

zlabel 


(add 
to all 
labels) 
blk 


Section C 
Section D 
zlabel 


n.a. GEM library suppl e 
Expand Implementation is 
code s tandard but 
in full translation depend^ 
an the availability 
of the library used,] 
follow example 
" L) 


TEXT be 


BSS 

label 


ds 


. apendix 

lete any period 


c irective prefix, 
sfo macro facilities) 
aut a full set of 
< 1EM libraries. Look 
at example appx L 
:o see sheer power 
and how difficult 
i ranslation will be 
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The above table will help to eliminate some of the more straight-forward 
program conversion problems, those that remain are likely to be due to the use of 
assembler specific directives and or libraries (especially label errors). 

If a program is published, one assumes that any include file data will be 
generally available and can either be appended as an include file or the code 
integrated with the main program block of code. 

If your assembler does not have VDI and AES libraries, then to use GEM you 
will have to create the arrays and load the addresses as shown in the assembler 
GEM example appendix L 

The chart is limited to simple conversions. Once include files and global label 
definitions are used, you will need to assemble the program, generate a list of the 
missing external labels and hopefully find them in the examples Appendix L and 
or the call listings Appendix E. 


Numbers 

The following shows the standard presentation of the various numeric types: 


Octal 

@nnn 

n=0 to 

Binary 

%xxxxxxxx 

x=0 or 

Decimal 

nnnn 

n=0 to 

Hexadecimal 

$nnnn 

n=0 to 
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Basic calling procedures 

Basic calling procedures for simple source files assembled (and linked) 
without libraries. 


Kseka 

SEKA> r 

FILENAME> filename 
SEKA> a 
OPTIONS> v 


Instruction to read source file from disc 
File to read (default .S extension) 
Instruction to assemble source 
Option to view assembly on screen 


SEKA> wo Instruction to write output program 

FILENAME> filename File to write (default .PRG extension) 

Hisoft Menu driven, place cursor over instruction and click 

Option > Assemble 

Option dialog box 
Binary filename xxxxx.prg 
Listing option boxes (none/screen/printer/ disc) 

Assemble /cancel boxes 

GST Menu driven, place cursor over instruction and click, OR double click the 
TTP program file and enter the filename as the parameter: 

ASM.PRG filename to produce a list file and filename.BIN from a default 

.ASM extension file 

LINK.PRG filename to produce a .MAP file and filename.PRG from a 

default .BIN extension file 

Metacomco The program files are installed as Tos Takes Parameters (TTP), 
double click and enter input file: 

ASSEM.PRG filename Assembles filename.asm to produce a GST format 

output file 

LINK.PRG filename Produces a .MAP file and filename.PRG from a 

default .BIN extension file 

Digital Research The program files are installed as TOS Takes Parameters and 
the file data entered into the parameter box. 

AS68.PRG filename.S Produce binary file 

LINK68.PRG filename. 68K = filename.o Produce relocatable file 

RELMOD.PRG filename Produce absolute file 
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Executable file sizes (bytes) 


Natural compilations with no optimisation extensions called. 


Program Page # 

D.R 

Seka 

Hisoft 

GST Me 

tacomcc 

GEM error message L 7 

777 

- 

- 

- 

781 

Assembler GEM L8-17 

1651 

1734 

3170 

3170 

3016 

3170 

TOS colour demo LI 6 

145 

162 

246 

246 

235 

248 

TOS VT52 screen L18-19 

194 

202 

202 

192 

202 

TOS sound program L20-22 

324 

331 

591 

591 

586 

591 

Line-A sprite program L25-26 

296 

314 

394 

394 

374 

392 


The Metacomco file sizes are for files linked via the GST linker except for the 
'GEM error message' which used the DR linker. 

The Digital Research files are absolute files and therefore presumably nearer 
the minimum possible size. 


(a secondary figure is given which specifically sets all text and data sections 
initialised to provide standard file size compilation comparisons, not all of the 
test assemblers can handle an uninitialised section) 
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C compilers 


Many C compilers have been developed for the ST range of computers, 
enabling the ST programmer to produce modular, well documented, easily 
maintained code that may be ported to other C systems with a minimum of 
effort. 


Although achieving the same end result, the C compilers differ considerably 
in the way that they attain that result. I give three examples of the compilation 
process: 


Source text 

Preprocessor 

Intermediate file 

Parser 

Intermediate code file 

Code generator 

Assembler text 

Assembler 

Object file 

Libraries 

Link68 


Resolve #define and 
#include statements 


Produce an intermediate 
code file 


Generate assembly 
language source file 


Create an object file 


Link object file with 
run-time library and 
operating system files 


Executable program file 

Relocator 


Change the relocatable 
information to absolute 
data 


Absolute program file 
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GSTC compiler 

Source text 

C compiler 

Assembler text 

J Assembler 

Relocatable binary file 

| Libraries 
Link68 

Executable program file 

Metacomco Lattice C 

Source text 

LC1 compiler 
Intermediate quad file 

LC2 compiler 


Binary file (GST or TOS format) 
| Libraries 
Link68 


Resolve # define and 
#include statements, 
produce assembly source 
file. 


Produce a relocatable 
binary file 


Link object file with 
run-time library and 
operating system files 


Produce an intermediate 
file of logical records 


Produce either an object 
file (DR linker or a 
relocatable binary file 
(GST linker) 


Link object file with 
run-time library and 
operating system files 


Executable program file 
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Those programmers who wish to program the Atari ST in C may find the 
following brief notes helpful: 

Unlike nearly all of the commercial assemblers, the C compilers supply a full 
set of GEM and system libraries. Commercial C compilers for the Atari ST will in 
general adhere to the GEM VDI and GEM AES function names used in this book, 
usually only the first 8 characters being significant. The compilers diverge 
considerably in use of parameter names, the call and parameters are therefore not 
provided here to avoid confusion. The manual of the C compiler you are using 
will provide a definitive list of the library routines available, interfaces, and the 
required parameter size, sequence and annotation. 

Many compilers will have additional features to greatly simplify the task of 
writing GEM programs; but bear in mind that the use of these 'super C' GEM 
functions may put a restraint on program portability. A definite decision should 
be made as to whether the programmer is writing portable code or simply 
writing a program. 

On a more general note; it is very much easier to develop programs on a 1 
Meg disk drive, which makes the larger drive well worth the small additional 
cost for those machines without the built-in drive. 
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Appendix L 


Example assembler programs 

GEM 


Application and accessory header file 

L.3 

GEM demonstration program 

L.8 

GEM demonstration assembly program 

L.9 

TOS 


Display demonstration program 

L.17 

TOS header file 

L.19 

Character printing program 

L.20 

Sound demonstration program 

L.22 

Line-A 


Line-A parameter table 

L.26 

Sprite demonstration 

L.28 
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Example programs 


General 

The programs presented in this section illustrate some of the techniques 
involved in accessing parts of the Atari ST operating system and also present 
general purpose header /include files. The programs are written as shells to 
which the programmer may add his/her own composition. 

It is not the intention to provide 'state of the art' programs, merely 
demonstrate access to the various parts of the operating system. Any attempt at 
definitive programming would rapidly succumb to the passage of time and tend 
to produce a book of listings. The main place to find quality programs will be the 
computer magazines, where programs developed from this and other books will 
appear as programmers quickly find new, smarter routes to access and use the 
ROM routines. 


Desktop accessories should be compiled as applications for debugging 
purposes as it is not possible to execute an accessory. 


Program conversion key 

n.a program not suitable for this assembler, 

xxx delete this line 

* use ; for Kseka, GST and Metacomco comments 
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GEM 


GEM application and accessory header file 


Digital Research (and Metacomco in CP/M 68K object mode) application and 
desk accessory files require a similar type of header source file construct to 
provide access to the GEM VDI and AES libraries, either as the first file in the DR 
link statement or as the beginning of a single block of assembler code. 

Part of this file determines the size of memory the application requires and 
returns the remainder to GEMDOS. Some Atari ST assemblers will provide 
similar code as a header/ initialisation file to permit the programmer to access the 
VDI and AES functions through their own integral libraries. 


* 

Digital Research 


* Hisoft 

GST 

Metacomco 

Seka 

* 



* n . a 

n . a 


n . a 

•k 

text 

* Text segment 

* 





globl _main 

* Make labels 

* 


. xde f 



globl _crystal 

* accessible to 

* 


. xde f 



globl _ctrl_cnts 

* external files 

* 


. xde f 



move .1 a7, a5 

* store stack (a5) 

* 





move.l #ustk,a7 

* set local stack 

* 




■k 

Desk accessories do not require the following lines 

of code 



* 

* 

which size memory and 

return the unused memory to GEMDOS 




move . 1 4 (a5) , a5 

* basepage address 

* 





move . 1 $c (a5) , dO 

* length of text 

* 





add . 1 $14 (a5) , dO 

* length of data 

* 





add. 1 $lc(a5) ,d0 

* length of BSS 

* 





add . 1 #$100, dO 

* basepage size 

* 





move .1 dO, - (sp) 

* retained mem len 

* 





move .1 a5, - (sp) 

* memory to modify 

* 





move dO, - (sp) 

* dummy word 

* 





move #$4a,-(sp) 

* reallocate to GEM* 





trap #1 

* function number 

* 




* 

add . 1 #12, sp 

* tidy stack 

★ 




* 

* 

Main program call 







jsr _main 

* main program code 

* 





move .1 # 0 , - ( a 7 ) 

* return to GEMDOS 

* 





trap #1 

* function call 

* 
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* 

* Digital Research * Hisoft . 

* 

* GEMAES calls link through _crystal 


_crystal : 

move .1 4 (a7) , dl 

move . w #200, dO 

trap #2 

rts 

bss 

even 

* 

ds.l 64 
ustk: ds.l 1 
* 

data 

even 

* 

_ctrl_cnts 

* 

* Application manager 


address of AES pblk* 
GEMAES function #* 
function call * 
return * 

block storage seg* 
force even boundary* 

* 

* 

* 


dc.b 0,1,0 * APPL_INI 10* 

dc.b 2,1,1 * APPL_REAd 11* 

dc.b 2,1,1 * APPL_WRIte 12* 

dc.b 0,1,1 * APPL_FINd 13* 

dc.b 2,1,1 * APPL_TPLay 14* 

dc.b 1,1,1 * APPL_TREcord. . .15* 

dc.b 0,0,0 * * 

dc . b 0 , 0 , 0 * * 

dc . b 0 , 0 , 0 * * 

dc.b 0,1,0 * APPL_EXIt 19* 

* 

* Event manager 

* 

dc.b 0,1,0 * EVNT_KEY 20* 

dc.b 3,5,0 * EVNT_BUTton 21* 

dc.b 5,5,0 * EVNT_MOUse 22* 

dc.b 0,1,1 * EVNT_MESsage. . .23* 

dc.b 2,1,0 * EVNT_TIMe 24* 

dc.b 16,7,1 * EVNT_MULti 25* 

dc.b 2,1,0 * EVNT_DCLick 26* 

dc . b 0 , 0 , 0 * * 

dc . b 0 , 0 , 0 * * 

dc . b 0 , 0 , 0 * * 


GST Metacomco 


XXX 


XXX 
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* 

* Digital Research * Hisoft 

* 

* Menu manager 

dc . b 1/1,1 * MENU_BAR 30* 

dc.b 2,1,1 * MENU_ICHeck 31* 

dc.b 2,1,1 * MENU_IENable ... 32 * 

dc.b 2,1,1 * MENU_TNOrmal. . .33* 

dc.b 1,1,2 * MENU_TEXt 34* 


dc.b 1,1,1 * MENU_REGister . . 35* 

dc.b 0,0,0 * * 

dc.b 0,0,0 * * 

dc.b 0,0,0 * * 

dc.b 0,0,0 * * 

* 

* Object manager 


dc.b 2,1,1 * OBJC_ADD 40* 

dc.b 1,1,1 * OBJC_DELete 41* 

dc.b 6,1,1 * OBJC_DRAw 42* 

dc.b 4,1,1 * OBJC_FINd 43* 

dc.b 1,3,1 * OBJC_OFFset 44* 

dc.b 2,1,1 * OBJC_ORDer 45* 

dc.b 4,2,1 * OBJC_EDIt 46* 

dc.b 8,1,1 * OBJC_CHAnge .... 47 * 

dc . b 0 , 0 , 0 * * 

dc . b 0 , 0 , 0 * * 


* Form manager 


dc.b 1,1,1 

* FORM DO 

50* 

dc.b 9, 1, 1 

* FORM DIAlog . . . 

51* 

dc.b 1,1,1 

* FORM ALErt 

52* 

dc.b 1,1,0 

* FORM ERRor .... 

53* 

dc.b 0,5,1 

* FORM CENtre. . . 

54* 

dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

* 

dc.b 0, 0,0 

* 

* 

dc.b 0, 0,0 

* 

* 

Dialog manager 



dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

* 

dc.b 0,0,0 

* 

★ 

dc.b 0,0,0 

* 

* 

dc.b 0, 0,0 

* 

* 


GST Metacomco 


Seka 
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* 

* Digital Research 

k 

* Graphics manager 



dc . b 

4 , 3/0 

* 


dc.b 

8 , 3,0 

* 


dc.b 

6 , 1,0 

* 


dc.b 

8 , 1,0 

* 


dc.b 

o 

i — i 
CO 

* 


dc.b 

4 , 1,1 

* 


dc.b 

3 , 1,1 

* 


dc.b 

0 , 5,0 

* 


dc.b 

1 , 1,1 

* 


dc . b 

0 , 5,0 

* 

* 




* 

Scrap manager 


★ 

dc.b 

0 , 1,1 

★ 


dc.b 

0 , 1,1 

* 


dc . b 

o 

o 

o 

* 


dc.b 

o 

o 

o 

* 


dc.b 

o 

o 

o 

* 


dc.b 

o 

o 

o 

* 


dc.b 

o 

o 

o 

* 


dc.b 

o 

o 

o 

* 


dc.b 

0 , 0,0 

* 


dc.b 

o 

o 

o 

* 

* 




* 

File selector manager 


* 

dc . b 

0 , 2,2 

* 


dc . b 

0 , 0 , 0 

* 


dc . b 

0 , 0 , 0 

* 


dc.b 

0 , 0,0 

* 


dc.b 

0 , 0,0 

* 


dc.b 

0 , 0 , 0 

* 


dc.b 

0 , 0, 0 

* 


dc . b 

o 

o 

o 

* 


dc.b 

o 

o 

o 

* 


dc . b 

0 , 0, 0 

* 

* 




* 

Window manager 


* 

dc . b 

5 , 1,0 

* 


dc.b 

5 , 1,0 

* 


dc.b 

1 , 1,0 

* 


dc.b 

1 , 1 , 0 

* 


dc.b 

2 , 5,0 

* 


dc.b 

6 , 1,0 

•k 


dc.b 

2 , 1,0 

k 


dc.b 

1 , 1 , 0 

k 


dc.b 

6 , 5,0 

k 


dc.b 

o 

o 

o 

k 


* Hisoft 


GRAF_RUBbe rbox .70* 
GRAF_D RAgb o x ... 7 1 * 
GRAF_MOVebox ... 72 * 
GRAF_GROwbox . . .73* 
GRAF_SHRinkbox. 74 * 
GRAF_WATchbox . . 75 * 
GRAF_SLIdebox ..76* 
GRAF_HANdle . ... 77 * 

GRAF_MOUse 78* 

GRAF MKState . . .79* 


SCRP_REAd 80* 

SCRP_WRIte 81* 

* 

* 

* 

* 

* 

* 

* 

* 


FSEL_INPut 90* 

* 

* 

* 


WIND_CREate. . .100* 

WIND_OPEn 101 * 

WIND_CLOse 102* 

WIND_DELete . . .103* 

WIND_GET 104* 

WIND_SET 105* 

WIND_FINd 106* 

WIND_UPDate. . .107* 
WIND CALc 108* 


GST Metacomco 
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* Digital Research 

* 

* Resource manager 

* 

dc.b 0,1,1 
dc.b 0, 1, 0 
dc.b 2,1,0 
dc.b 2,1,1 
dc.b 1,1,1 
dc.b 0,0,0 
dc.b 0,0,0 
dc.b 0,0,0 
dc.b 0,0,0 
dc.b 0,0,0 

* 

* Shell manager 

* 

dc.b 0, 1,2 
dc.b 3,1,2 
dc.b 1,1,1 
dc.b 1,1,1 
dc.b 0,1,1 
dc.b 0, 1,2 
* * 

end 


* RSRC_LOAd 110* 

* RSRC_FREe Ill* 

* RSRC_GADdress . 112 * 

* RSRC_SADdress . 113 * 

* RSRC_OBFix . . . .114* 

* * 

★ * 

* * 

* * 

* * 

* SHEL_REAd 120* 

* SHEL_WRIte . . . .121* 

* * 

* * 

* SHEL_FINd 124* 

* SHEL ENVrn 125* 


Hisoft 


GST Metacomco Seka 


The object file is used as the first file in the link to produce an Atari ST 
program file, say myprog, that accesses the DR GEM libraries i.e: 
either DR 

as68 -1 -u apstart.s 

or Metacomco 


assem.prg apstart.asm opt j 


followed by the linking of the main program file (see following example) to 
the header and the DR library files. 


Link68 [u] myprog . 68=apstart myprog. o vdibind aesbind 
Relmod myprog 

Delete all temporary files, leaving either an application file myprog.prg 
(which may be run by double clicking the icon in the directory listing) or an 
accessory file which must be renamed myprog.acc. Reboot the system and run 
the file by clicking the icon in the list of 'Desk' accessory files. 


Remember to initially compile and run accessories as applications to debug 
them. 
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GEM demonstration program 


To use GEM directly, push the function parameters onto the stack in the 
order given by the GEM VDI and GEM AES tables, ensuring that the correct size 
of parameter is pushed. 

The following program, which may be written in either DR or Metacomco 
macro assembler but must use the DR link68 linker, lists in descending order the 
TOS error codes in dialog boxes, the user stepping from one code to the next via 
the mouse or the 'return' key. 


* Digital Research 

* 

* Demo GEM program 

* 

globl _main 
globl _form_err 
globl _appl_ini 
globl _appl_exi 

* 

text 

* 

_main : 

jsr _appl_ini 

move.w #63/ d4 
loop: move.w d4/temp 
move . w d4 / - (sp) 
jsr _form_err 
add. w #2/ sp 
move.w temp, d4 
dbra d4/ loop 
jsr _appl_exi 
rts 

bss 

* 

temp: ds.w 1 
* 

end 


* Error start # 

* Save it 

* Stack it 

* What is it 

* Tidy it 

* Recover it 

* and next 

* Controlled exit 


* Hisoft . GST 

* n . a . n . a 

* 

* 


* 

* 

* 

* 


* 

* 


* 

* 


Metacomco Seka 
. n. a 


. xdef 
. xref 
. xref 
. xref 

. The 
Metacomco 
. external 
. symbol 
. names 
. are 
. limited 
. to 8 
characters 
. i .e 

_form_er 

_appl_in 

_appl_ex 


The file may be assembled using either 

DR- 


as68 -1 -u -p myprog.s 

or Metacomco- 

assem myprog.asm opt j 


Both programs are linked with the Digital Research link68 linker i.e: 

link68 [s,u] myprog . 68k=apstart , myprog . o, aesbind 

and finally relocated by: 

relmod myprog 
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Example Programs 


GEM demonstration assembly program 

It is possible to write assembly language programs that do not use the DR 
GEM bindings but simply access the functions via the Extended BDOS TRAP #2 
calls. The following example shell shows a technique that will enable the 
programmer to create a window, do some work in it, and then make a controlled 
exit. 


Note: Although the window is created with the sizing diamond and sliders, 
no code has been written to handle the screen managers requests for change; if 
these functions are activated they are ignored. If the cursor is active (as in this 
program) and covers part of the foreground content of the screen when the 
program is loaded, it will leave a hole when moved. 

* Digital Research * Hisoft . GST Metacomco Seka 

* 

* Assembler GEM program 

* Size the job and free back to GEMDOS unused memory 

* 


text 

move .1 a7, a5 

* 

curr - a5 

* XXX 

★ 

move . 1 #ustk, a7 

* 

set local stk 

* 

move .1 4 (a5) , a5 

* 

get base page 

* 

move . 1 $c (a5) , dO 

* 

text segment 

* 

add . 1 $14 (a5) , dO 

* 

data segment 

* 

add. 1 $lc (a5) , dO 

h 

uninitialized 

* 

add . 1 #$100, dO 

* 

basepage size 

* 

move . 1 dO, - (sp) 

* 


* 

move . 1 a5, - (sp) 

* 


* 

move dO, - (sp) 

★ 


* 

move #$4a, - (sp) 

* • 

free unused mem 

* 

trap #1 

* 


* 

add.l #$c,sp 

•k 

tidy stack 

* 

jsr start 

* 


* 

move .1 #$0, - (sp) 

* 

ret to GEMDOS 

* 

trap #$1 

* 


* 


* Technique for setting up VDI & AES arrays 

* 

* Initialize AES arrays 

* 

start : 

* 

jsr ini_aes * 


section c 


code 


L.9 




The Concise Atari ST Reference Guide 


* Digital Research 

* 

* Call APPL_INI (1st call) 

* 

appl_ini : 

move.w #$a, control 
move.w #$0, control+2 
move.w #$1, control+4 
move.w #$0, control+6 
jsr aes 
tst . w int_ou 
bpl graf_han 
rts 


* Hisoft 

* pg 5.6 


GST 


Metacomco 


* Call GRAF_HAN to get name of the currently opened window, pg 5.26 

* 

graf_han : 

move.w #77, control * 

move.w #$0, control+2 * 

move.w #$5, control+4 * 

move.w #$0, control+6 * 

jsr aes * 

move.w int_ou, handle * 

* 

* Initialize VDI arrays 

* 

jsr ini_vdi * 


* Open virtual workstation 

* 

v_opnvwk : 

move.w #100,contrl 
move.w #0,contrl+2 
move.w #ll,contrl+6 
move.w handle, contrl+12 


* pg 4.9 


11 input parameters 

move.w #1, intin 
move.w #l,intin+2 
move.w #l,intin+4 
move.w #l,intin+6 
move.w #l,intin+8 
move.w #l,intin+10 
move.w #l,intin+12 
move.w #l,intin+14 
move.w #l,intin+16 
move.w #l,intin+18 
move.w #2,intin+20 
jsr vdi 


*drive id 
*line type 
*line color 
♦marker type 
♦marker color 
♦text face 
♦text color 
♦interior fill 
♦fill index 
♦fill color 
♦NDC/RC 


* Save virtual screen workstation device handle 

* 

move.w contrl+12 , vhandl ♦ 

tst.w contrl+12 * 

beq appl_exi * 


L.1 0 
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Example Programs 


* Digital Research * Hisoft . GST 

* 

* Test here for screen resolution and number of colors available 

* (even in mono) . Load appropriate resource file using the AES 

* RSRC_LOA call if necessary. 


* Get max possible size of window 


max_wind : 

move.w vhandl, int_in 

move.w #7,int_in+2 * sizes 

jsr wind_get 

tst . w int_ou 

beq appl_exi 

h 

* Calculate work area of window 

* 

move.w #0,int_in 
jsr wind_cal 
tst . w int_ou 
beq appl_exi 

* 

* Calc new window bordered area 

* 

move.w #l,int_in 
jsr wind_cal 
tst . w int_ou 
beq appl_exi 


* Alloc space for full size window 

★ 

wind_cre : 

move.w #100, control 
move.w #$5, control+2 
move.w #$1, control+4 
move.w #$0, control+6 

* 

move.w #$0f f f , int_in * edges 

move.w int_ou+2, int_in+2 * xl 
move.w int_ou+4, int_in+4 * yl 
move.w int_ou+6, int_in+6 * x2 
move.w int_ou+8, int_in+8 * y2 
jsr aes 


move.w int_ou, whandl 
tst . w int_ou 
beq appl_exi 

★ 

* Open window at last 

* 

wind_ope : 

move.w #101, control 
move.w #$5, control+2 
move.w #$1, control+4 
move.w #$0, control+6 


* 

* 

* 

* 

* 


* 

* 

* 

* 


* pg 5.29 


* 

* 

* 

* 


* 

★ 

* 


* 

* 

* 


* pg 5.29 


* 


Metacomco 


Seka 
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* Digital Research 


Hisoft . 


GST Metacomco 


* Absolute parameters 

* 

move . w whandl, int_in * 

move.w #0,int_in+2* xl * 

move . w #0,int_in+4* yl * 

move.w #280/ int_in+6 * x2 * 

move.w #160/ int_in+8 * y2 * 

jsr aes * 

tst.w int_ou * 

beq appl_exi * 

* 

* Do something on the screen, this is where your program starts. 


* Set screen parameters 

* 

vsf_inte : 

move.w #23,contrl 
move.w #0,contrl+2 
move.w #l,contrl+6 
move.w whandl, contrl+12 

* 

move.w #1/ intin * solid 

jsr vdi 

* Style 

* 

vsf_styl : 

move.w #24,contrl 
move.w #0,contrl+2 
move.w #l,contrl+6 
move.w whandl, contrl+12 

* 

move.w #l,intin * n.a 

jsr vdi 

* 

* Colour 

* 

vsf_colo : 

move.w #25/Contrl 
move.w #0,contrl+2 
move.w #l/Contrl+6 
move.w whandl, contrl+12 

* 

move.w #1/ intin * black 
jsr vdi 

* 

* Set mouse style 

* 

graf_mou : 

move.w #78/ control 
move.w #$1/ control+2 
move.w #$1/ control+4 
move.w #$1/ control+6 


pg 4.15 


pg 4.15 


pg 4.15 


pg 5.26 


Seka 
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* Digital Research 


Hisoft . 


Metacomco 


move . w #$0,int_in 
jsr aes 
tst . w int_ou 
beq appl_exi 

* 

* Get position of window work area 

* 

where : 

move.w whandl, int_in 

move.w #4,int_in+2 * work area 

jsr wind_get 

tst . w int_ou 

beq appl_exi 


* Get coordinates within work area 

* 

add.w #35,int_ou+2 * 

add . w #35,int_ou+4 * 

sub.w #50/int_ou+6 * 

sub.w #50,int_ou+8 * 

* 

* Draw a shape from those coords * pg 4.12 

■k 

v_rfbox: 

move.w #ll,contrl * 

move.w #2,contrl+2 * 

move.w #0,contrl+6 * 

move.w #9,contrl+10 * 

move.w whandl, contrl+12 * 

* 

* Absolute coords — not window the reason for this patch 

move.w int_ou+2/ ptsin * 

move.w int_ou+4, ptsin+2 * 

move.w int_ou+6, ptsin+4 * 

move.w int_ou+8, ptsin+6 * 

* 

jsr vdi * 

* 

* Wait for a sign - about 1 minute * pg 5.9 

evnt_tim: 

move.w #24/ control* 

move.w #$2/ control+2 * 

move.w #$1, control+4 * 

move.w #$0, control+6 * 

* 

move.w #$f f f f , int_in *Lo * 

move.w #$0000, int_in+2 *Hi * 

jsr aes * 


End of program, shut the window in a controlled manner 


Seka 
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* Digital Research 

* 

* Close v_scrn Stop o/p (Shut window down) 

★ 

v_clsvwk : 

raove.w #101,contrl 
raove.w #0,contrl+2 
move.w #0,contrl+6 
move.w vhandl, contrl+12 

* 

* Close window 

* 

wind_clo : 

move.w #102, control 
move.w #$1, control+2 
move.w #$1, control+4 
move.w #$0, control+6 

* 

move.w whandl, int_in 
jsr aes 
tst . w int_ou 
beq appl_exi 

* 

* Deallocate space and handle 

* 

wind_del : 

move.w #103, control 
move.w #$1, control+2 
move.w #$1, control+4 
move.w #$0, control+6 

* 

move.w whandl, int_in 
jsr aes 
tst . w int_ou 
beq appl_exi 

* 

* Call APPL_EXI (Last call) 

* 

appl_exi : 

move.w #19, control 
move.w #$0, control+2 
move.w #$1, control+4 
move.w #$0, control+6 

* 

* Subroutines 

* 

* Get window data 

* 

wind_get : 

move.w #104, control 
move.w #$2, control+2 
move.w #$5, control+4 
move.w #$0, control+6 


Hisoft 


pg 4.9 


GST 


Metacomco 


* pg 5.29 


pg 5.29 


* pg 5.7 


* pg 5.30 


Seka 
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* Digital Research * Hisoft . GST Metacomco Seka 

* 


move.w vhandl, int_in * rem 

move.w #7,int_in+2 * out 

jsr aes 
rts 


* Calculate window work area based on facilities: title, 

* scroll bar etc. * pg 5.32 


wind cal : 



move.w #108, control 


* 





move.w #$6, control+2 


* 





move.w #$5, control+4 


* 




* 

move.w #$0, control+6 


* 




* 

move.w #0,int_in 

* rem out 

* 





move.w #$0f f f , int_in+2 

* edges 

* 





move . w int_ou+2 , int_in+4 

* xl 

* 





move . w int_ou+4 , int_in+6 

* yl 

* 





move.w int_ou+6, int_in+8 

* x2 

* 





move.w int_ou+8, int_in+10 

*y2 

* 





jsr aes 


* 




* 

rts 


* 




* VDI 

* 

parameter block call 






vdi : 

move.l #contrl,pblock * 

reset 

* 





move.l #pblock,dl 


* 





move.l #115, dO 


* 





trap #$2 


* 




* 

rts 


* 




* AES 

* 

parameter block call 






aes : 

move.l #control,__c * 

reset 

* 

. zc 

. zc 



move.l #_c,dl 


* 

. #zc 

. #zc 



move.l #200, dO 


* 





trap #$2 


* 




★ 

rts 


★ 




* Set 

* 

up AES array 






ini_aes : 







move.l #control,_c 


* 

. zc 

. zc 



move.l #global,_c+4 


* 

. zc+4 

. zc+4 



move.l #int__in,_c+8 


* 

. zc+8 

. zc+8 



move.l #int_ou,_c+12 


* 

. zc+12 

. zc+12 



move.l #addr_in,_c+16 


* 

. zc+16 

. zc+16 



move.l #addr_ou,_c+20 


* 

. zc+20 

. zc+20 



rts 


* 
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* Digital Research 

* 


* Set up VDI array 

* 


ini_vdi : 

move.l #contrl, pblock 
move.l #intin, pblock+4 
move.l #ptsin,pblock+8 
move.l #intout, pblock+12 
move.l #ptsout/ pblock+16 
rts 


Hisoft . GST Metacomco 


* Make space for the arrays. You must ensure these are large 

* enough to hold the array's data. Be especially careful regarding 

* the spelling of the array names. 'New TOS' requires larger VDI 

* arrays than previous versions of the OS. 


Seka 


bss 



* XXX 

section d 


. data 

even 

* 


* XXX 


XXX 

. XXX 

. XXX 


ds . 1 

256 

* 




. blk.l 

ustk : 
* 

ds.l 

1 

* 




. blk.l 

pblock : 

ds.l 

5 

* 




. blk.l 

contrl : 

ds . w 

12 

* 




. blk.w 

intin : 

ds . w 

30 

* 




. blk.w 

ptsin : 

ds . w 

30 

* 




. blk.w 

intout : 

ds . w 

45 

* 




. blk.w 

ptsout : 
* 

ds . w 

12 

* 




. blk.w 

handle : 

ds . w 

1 

* 




. blk.w 

vhandl : 

ds . w 

1 

* 




. blk.w 

whandl : 
* 

ds . w 

1 

* 




. blk.w 

_c : 

ds.l 

6 

* 


zc 


. zc blk.l 

control : 

ds . w 

5 

* 




. blk.w 

global : 

ds . w 

16 

* 




. blk.w 

iiit_in : 

ds . w 

16 

* 




. blk.w 

int_ou: 

ds . w 

7 

* 




. blk.w 

addr_in: 

ds . 1 

2 

* 




. blk.l 

addr_ou : 

ds.l 

1 

* 




. blk.l 


end 


The program may be assembled and linked (if required) using the assembler 
calling procedures outlined in AppendixJC 
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TOS 


Display demonstration program 

The following program shows a typical Atari TOS file, which simply inverts 
the current mono display color for those programmers who,like myself, prefer 
white on black or toggles the border of a color display. 


* Digital Research 

* 

* Demo Atari TOS program 

* 


text 

* 

move . 1 a7,a5 
move.l #ustk,a7 
move .1 4 (a5) , a 5 
move .1 $c(a5) , dO 
add. 1 $14 (a5) , dO 
add. 1 $lc(a5) ,d0 
add . 1 #$100, dO 
move . 1 dO, - (sp) 
move . 1 a5, - (sp) 
move dO, - (sp) 
move #$4a, - (sp) 
trap #1 
add.l #$c,sp 
jsr start 
move .1 #$0, - (sp) 
trap #$1 

* 

start : 

clr . 1 - (sp) 
move . w #32, - (sp) 
trap #1 
move .1 dO, al 
move.w #-l,d0 
jsr newcol 
eori #l,d0 
jsr newcol 

exit : 

move .1 al, - (sp) 
move.w #32, - (sp) 
trap #1 

move.l #0,-(a7) 
trap #1 


* set - a7 


* free unused 

* back to GEM 

* jump to prg 

* terminate 


* set super 

* get/set col 


* set user 


* Hisoft . GST Metacomco Seka 


* xxx section c 


code 


* 

* 
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* Digital Research 


newcol : 

move . w dO,-(sp) * get color 

move . w #0, - (sp) 

move . w #7, - (sp) 

trap #14 

add . w #6, sp 

rts 

* 

bss 

ds.l 20 
ustk: ds.l 1 
* 

end 


Hisoft . GST Metacomco 


xxx section d 


The above program is assembled and linked without any other files. 


Seka 


data 

blk.l 

blk.l 
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Example Programs 


TOS header file 


The following shows a typical Atari TOS header file that may be incorporated 
in a user-written program to provide access to the base page offset variables. 


* 

* Base page format initialised by BDOS 




* 


ltpa 

equ 

0 

* 

Low TPA address 

htpa 

equ 

4 

* 

High TPA address + 1 

lcode 

equ 

8 

* 

Text segment start 

codelen 

equ 

12 

* 

Length of text segment 

ldata 

equ 

16 

* 

Initialized data segment start 

datalen 

equ 

20 

* 

Length of initialized data 

lbss 

equ 

24 

* 

BSS segment start 

bsslen 

* 

equ 

28 

* 

Length of uninitialized data 


* either GEMDOS 

* 


*env 

equ 

44 

* 

Environment string pntr 

(GEMDOS) 

* or Atari OS 

f reelen 

equ 

32 

* 

Free memory length after 

BSS 

ldriv 

equ 

36 

* 

Drive from which program 

loaded 

resvd 

equ 

37 

* 

Reserved 


fcb2 

equ 

56 

* 

2nd parsed fcb 


fcbl 

* 

equ 

92 

* 

1st parsed fcb 


* common tail 

command 

equ 

128 

★ 

Command tail 



Although it is good practice to size the memory requirements of you 
program and return the unused memory to GEMDOS, programs can be writte 
without if they return to the GEM desktop. 

GEM allocates all the memory to the program, only if it multitasks or cal 
and loads another program is there any real need to return spare memory. 
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Character printing program 

This simple program demonstrates some of the methods available for 
printing to the VT52 screen. The compiled program may be installed as: 

A 'GEM program' - the busy bee cursor will appear in the display and leave a 
hole when moved. 

A 'TOS program' - with flashing cursor, the cursor may be hidden quite 
easily by incorporating within the 'prdat' string the hide cursor escape code as 
specified in Appendix C. 

* Digital Research * Hisoft . GST Metacomco Seka . 


* Monochrome TOS VT52 screen print program (0,0 to 24,79) 


* (For colour, set max print width in 'prdat' to 39) 

* 

text * xxx section c 

* GEM BIOS type print 

* 

clr.l d4 * Clear d4 * 

clr.l d5 * Clear d5 * 

lea prdat, a4 * Get data address * 

move.b (a4),d4 * Data count -1 * 

cloop: 

adda.l #l,a4 * Get next * 

move.b (a4),d5 * Getchar byte * 

move.w d5,-(sp) * Stack char.w * 

move.w #2,-(sp) * Send to console * 

move.w #3,-(sp) * Set bconoutO * 

trap #13 * Call it * 

add.w #6,sp * Tidy stack * 

dbra d4, cloop * loop for next * 

* 

* GEMDOS type print 


lea mess, aO 

* 

GetASCII string 

* 

move .1 aO, - (sp) 

* 

Stack it 

* 

move.w #9, - (sp) 

★ 

set conws () 

★ 

trap #1 

* 

Call it 

* 

add . w #6, sp 

* 

* 

Tidy stack 

* 

move.l #200, dl 

* 


* 

exlp: 

move.l #-l,d0 

* 

Wait 

* 

dloop: 

dbra dO, dloop 

* 


* 

dbra dl,exlp 

* 


* 

move.l #0,-(a7) 

* 

GEM return 

* 

trap #1 

* 


* 

rts 

* 

Return 

* 


code 


L.20 



Example Programs 


* Digital Research 


Hisoft . GST Metacomco Seka 


data * xxx section dl 

even * xxx . xxx . xxx 

* VT52 screen location character equivalents 

* 

*!"#$%&'() * + / 0123456 

* 0, 1, 2, 3, 4, 5, 6, 1, 8, 9, 10, 11, 12, 13, 14,15, 1 6, 11, 18, 19, 20, 21, 22 

* 

*7 8 9 < = >?@ABC DEFGHIJ 

*23,24, 25,26, 27,28/29/30, 31/32,33/34/35/36/ 37 ,38/39, 40,41,42 

*KLMNOPQRSTUVW XYZ[\] 

* 43, 4 4, 45, 4 6, 47, 4 8, 4 9, 50, 51, 52, 53, 5 4, 55, 56, 57, 58, 5 9, 60, 61 


* A _'abcdefghi jklmno 

* 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74,75, 76, 77, 78, 79 

* Data string to print (See Appendix C for codes) 


section d2 


prdat :dc .b 
dc . b 

50 

27, 

E' 

* 

* 

Clear screen 

dc . b 

27, 

b' , 0 

* 

foregnd col white 

dc.b 

27, 

c' , 1 

* 

backgnd col black 

dc . b 

27, 

Y 0,0' 

* 

Set cursor at 0,0 

dc . b 

27, 

Y ! ! 1 , 1 ' 

* 

Set cursor at 1,1 

dc.b 

27, 

’b' , 1 

* 

foregnd col black 

dc.b 

27, 

’ c' , 0 

* 

backgnd col white 

dc . b 

27, 

Y8f24, 69' 

1 * 

Set curs 0 24,69 

dc . b 

27, 

'P' 

* 

Inverse video 

dc . b 

27, 

' I' 

•k 

Up 1 line 

dc.b 

' hi 

j • 

* 

Say something witty 

dc.b 

27, 

r Y, 4 ' 

* 

set cursor at 12,20 

dc . b 

27, 

' q' 

* 

Reset video 


* Print null terminated string - uses ASCII & control codes 


dc.b 

' hello' 

* 

Alternative print 

dc . b 

10, 10,7 

* 

method for screen 

dc . b 

' hello' 

★ 

printing . 

dc . b 

10 

* 

Text 

dc . b 

'hello' 

* 

linefeed 

dc . b 

10, 13 

* 

carriage return 

dc . b 

' hello' 

* 

and a bell 

dc . b 

0 

* 

End of string 

end 





. xxx 
. xxx 


. even 


. even 
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Sound demonstration program 


This program provides a basic introduction to 'sound' programming on the 
Atari ST; where experimentation with each of the sounds provided is perhaps the 
best approach to understanding the effects of each argument. 

Take care of the following general points: 

Userstack: Make sure it is large enough. It grows down in memory and it can 
overwrite the data area. 

Tinting: It is necessary to provide a delay before an exit back to GEMDOS, 
TOS could reallocate the sound data bytes space. 


* Digital Research 

★ 


* Hisoft . GST Metacomco 

* Experimental TOS sounds program 

★ 


* 

text 


* xxx section c 


move.l a7,a5 

* create 

* 


move.l #ustk,a7 

* space for 

★ 


move . 1 4 (a5) , a5 

* program 

* 


move . 1 $c (a5) , dO 


* 


add . 1 $14 (a5) , dO 


* 


add . 1 $lc (a5) / dO 


* 


add. 1 #$100, dO 


* 


move . 1 dO, - (sp) 


* 


move .1 a 5, - (sp) 


* 


move dO, - (sp) 


a 


move #$4a, - (sp) 


* 


trap #1 


a 

* 

add.l #$c, sp 


A 

start 

move.l #soundl,al 

* 

* 

* 

jsr dosound 

* 

* 


move.l #150, dl 

* 15 secs 

* 

loopo 

moveq #-l,d2 

* wait for 

* 

loopi 

dbra d2, loopi 

* finish 

* 

* 

dbra dl, loopo 


* 

exit : 

clr . 1 - (sp) 

* GEMDOS ret 

* 


trap #$1 


* 


rts 


A 
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* Digital Research 


* Hisoft . GST 


dosound: 

move .1 al, - (sp) 
move . w #32, - (sp) 
trap #14 
add.w #6, sp 
rts 

* 

bss 

even 

* 

ds.l 64 
ustk: ds.l 1 
* 

data 

even 

* * Bell 

soundl : 


* sound pointer 

* 

* 


* XXX 

* XXX 


* Large enough not * 

* to overwrite data* 

* XXX 

* XXX 


dc.b 

0, $34 

*\ chan A 


* 

dc.b 

1,0 

*/ 2150 hz 


★ 

dc . b 

2,0 

* \ chan 


* 

dc.b 

3, 0 

* / B 


* 

dc.b 

4,0 

*\ channel 


* 

dc.b 

5,0 

*/ C 


* 

dc.b 

6, 0 

* noise 


* 

dc.b 

7, $fe 

* enable A 

only 

* 

dc . b 

8, $10 

* enable A 

envelope 

* 

dc.b 

9,0 

* B off 


* 

dc.b 

10,0 

* C off 


* 

dc.b 

11,0 

*\Single attack 

★ 

dc.b 

12, $10 

**envelope 

shape 

* 

dc.b 

13, 9 

*/ 1 0 0 1 


* 

dc.b 

130, 100 

* delay 


* 


* sound2 : 


* Siren 


dc.b 0, $fe 

*\ chan A 

* 

dc.b 1,0 

*/ 440 hz High note 

! * 

dc.b 2,0 

* \ chan 

* 

dc.b 3,0 

* / B 

★ 

dc.b 4,0 

*\ channel 

* 

dc.b 5,0 

*/ C 

* 

dc.b 6,0 

* noise 

* 

dc.b 7, $fe 

* enable A only 

* 

dc.b 8, 11 

* A amplitude 

* 

dc.b 9,0 

* B off 

* 

dc.b 10,0 

* C off 

* 

dc.b 11,0 

*\ no 

* 

dc.b 12,0 

* | envelope 

* 

dc.b 13,0 

*/ shape 

* 

dc.b 130,20 

* 

* 


section dl 

. XXX 


section d2 

. XXX 


Metacomco 


XXX 


XXX 


Seka 


data 

XXX 

blk.l 

blk.l 

code 

XXX 
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Digital Research 


GST 


Metacomco 


dc.b 0, $56 
dc.b 1,1 
dc.b 130,20 


*\ chan A Low note * 
*/ 187 hz * 


dc.b 0, $fe, 1,0, 130, 20 
dc.b 0, $56, 1, 1, 130, 20 


*High note 
*Low note 


* silence 


dc.b 8, 0, 9, 0 
dc.b 130, 50 


A & B off 


sound3 : 


gunshot 


dc.b 0, 0, 1, 0,2, 0, 3, 0, 4, 0, 5, 0 
dc.b 6, 15 
dc.b 7,199 
dc.b 8,16 
dc.b 9, 16 
dc.b 10, 16 
dc.b 11,0 
dc.b 12,16 
dc.b 13,0 
dc.b 130,25 


* medium noise period 

* enable noise chans A,B & C 

* \ using * 

* | envelope * 

* / control * 

*\ envelope period * 

*/ * 

* one cycle decay * 


dc.b 8 , 0 , 9 , 0 
dc.b 130, 50 


* silence 

* A & B off 


* sound4 : 


* explosion 


dc . b 

(N 

O 

o 

o 

0,3, 

- 0, 4, 0, 5, 0 

* 

dc . b 

6, 10 

* 

noise period 

* 

dc.b 

7,199 

* 

enable noise chans 

dc . b 

8, 16 

* 

\ using 

* 

dc.b 

9, 16 

* 

1 envelope 

* 

dc.b 

10, 16 

* 

/ control 

* 

dc . b 

11,0 

* 

\ envelope period 

* 

dc . b 

12, 80 

* 

/ 

* 

dc . b 

13,0 

* 

one cycle decay 

* 

dc . b 

130, 120 

* 


* 


& C 


* silence 


dc.b 8,0,9,0,10,0* A B & C off 
dc.b 130,100 * 
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x Digital Research * Hisoft . 

* sound5: * whistle 


dc.b 0, 0, 1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0 
dc.b 7,254 * enable tone A only 

dc.b 8,15 * * 

dc.b 9,0,10,0,11,0,12,0,13,0 * 

dc.b 128,60 * Initial tempreg * 

dc.b 129,0,-2,40 * reg-step-end * 

dc.b 130,2 * * 

* 

* exit list 


dc.b 7,255,8,0 * off 

dc.b 255,0 * return 


end 


GST Metacomco Seka 


. even 
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Line-A parameter table 

The following is the complete list of the Line-A equates and functions. It may 
be used as a standard assembler header file to Line-A programs. 

*********************************************** 

A 

* Line-A parameter table 

A 

*********************************************** 

* 


V_CEL_HT 

equ 

-46 

* 

.w 

Pixel cell height 

V_CEL_MX 

equ 

-44 

A 

.w 

Max cells across -1 

V_CEL MY 

equ 

-42 

A 

.w 

Max cells high -1 

V_CEL_WR 

equ 

-40 

A 

.w 

Offset to next cell 

V_ C ° L _BG 

equ 

-38 

A 

.w 

Background index color 

V_COL FG 

equ 

-36 

A 

.w 

Foreground index color 

V_CUR_AD 

equ 

-34 

A 

.L 

Current cursor address 

V_CUR_OFF 

equ 

-30 

A 

.W 

Offset to 1st cell 

V_ C UR_CX 

equ 

-28 

A 

.w 

X cursor position 

V_ C UR_CY 

equ 

-26 

A 

.w 

Y cursor position 

V_CUR CNT 

equ 

-24 

A 

.B 

Cursor flash interval 

V_ C UR_TIM 

equ 

-23 

A 

.B 

Cursor countdown timer 

V_FNT AD 

equ 

-22 

A 

.L 

Font address 

V _FNT_ND 

equ 

-18 

A 

.W 

Last font ASCII code 

V_FNT_ST 

equ 

-16 

A 

.W 

1st font ASCII code 

V_FNT_ WR 

equ 

-14 

A 

.W 

Font width 

V _X_MAX 

equ 

-12 

A 

.w 

Max X pixel scrn value 

V _°FF_AD 

equ 

-10 

A 

.L 

Font offset table addr 

V_STATUS 

equ 

-6 

A 

.W 

Text status byte 

V _Y_MAX 

* 

equ 

-4 

A 

.w 

Max Y pixel scrn value 

VPLANES 

equ 

0 

A 

.w 

# video planes 

VWRAP 

equ 

2 

A 

.w 

# bytes/video 

CONTRL 

equ 

4 

A 

.L 

\ 

INTIN 

equ 

8 

A 

.L 

1 

PTSIN 

equ 

12 

A 

.L 

1 array pntrs 

INTOUT 

equ 

16 

A 

.L 

1 

PTSOUT 

equ 

20 

A 

.L 

/ 

COLBITO 

equ 

24 

A 

.W 

\ 1 * ) 

COLBIT1 

equ 

26 

A 

.W 

|2 * ) write 

COLBIT2 

equ 

28 

A 

• W 

|4 * ) color 

COLBIT3 

equ 

30 

A 

.W 

/ 8 * ) 

LSTLIN 

equ 

32 

A 

.w 

-1 

LNMASK 

equ 

34 

A 

.w 

VDI line style 

WMODE 

A 

equ 

36 

A 

.w 

Write mode 

XI 

equ 

38 

A 

.w 

\ 

Y1 

equ 

40 

A 

.w 

I coordinates 

X2 

equ 

42 

A 

.w 

| 

Y2 

* 

equ 

44 

A 

.w 

/ 

PATPTR 

equ 

46 

* 

.L 

Curr fill patt pntr 

PATMSK 

equ 

50 

A 

.W 

Len fill patt mask 

MFILL 

equ 

52 

A 

.w 

0_single plane 

CLIP 

equ 

54 

A 

.w 

0_no clipping 
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* 

XMINCL 

equ 

56 

* 

.w 

\ 

YMINCL 

equ 

58 

* 

.w 

1 Clipping 

XMAXCL 

equ 

60 

★ 

.w 

1 values 

YMAXCL 

equ 

62 

* 

.w 

/ 

XDDA 

equ 

64 

* 

.w 

txtblt x dda accum 

DDAINC 

equ 

66 

* 

.w 

txtblt scale factor 

SCALDIR 

equ 

68 

★ 

.w 

0_down 

MONO 

equ 

70 

* 

.w 

0 font monospaced 

SRCX 

equ 

72 

* 

.w 

\ Coords of char 

SRCY 

equ 

74 

★ 

.w 

/ in font form 

DESTX 

equ 

76 

* 

.w 

\ Coords of char 

DESTY 

equ 

78 

* 

.w 

/ on screen 

DELX 

equ 

80 

* 

.w 

Char width 

DELY 

equ 

82 

* 

.w 

Char height 

FBASE 

equ 

84 

* 

.L 

Font form pointer 

FWIDTH 

equ 

88 

* 

.w 

width 

STYLE 

equ 

90 

* 

.w 

style 

LITEMSK 

equ 

92 

* 

.w 

lighten text mask 

SKEWMSK 

equ 

94 

* 

.w 

skew text mask 

WEIGHT 

equ 

96 

* 

.w 

extra text width 

ROFF 

equ 

98 

* 

.w 

high offset skew 

LOFF 

equ 

100 

* 

.w 

low offset skew 

SCALE 

equ 

102 

* 

.w 

0 no scaling 

CHUP 

equ 

104 

* 

.w 

0 horiz orientation 

TEXTFG 

equ 

106 

* 

.w 

Text foreground color 

SCRTCHP 

equ 

108 

* 

.L 

Text effects buffer 

SCRPT2 

equ 

112 

★ 

.w 

Offset to scale buffer 

TEXTBG 

equ 

114 

* 

.w 

Text background color 

COPYTRAN 

equ 

116 

* 

.w 

Copy raster type flag 

SEEDABORT 

* 

equ 

118 

* 

.w 

Abort fill routine ptr 




* Line-A function 

* 

calls 



init 

equ $a000 


putpix 

equ init+1 

* put pixel 

getpix 

equ init+2 

* get pixel 

abline 

equ init+3 

* draw a line 

habline 

equ init+4 

* horizontal line 

rectfill 

equ init+5 

* draw filled rectangle 

polyfill 

equ init+6 

* draw 1 line poly fill 

bitblt 

equ init+7 

* bit block transfer 

textblt 

equ init+8 

* text block transfer 

showcur 

equ init+9 

* show mouse 

hidecur 

equ init+10 

* hide mouse 

chgcur 

equ init+11 

* transform mouse form 

unsprite 

equ init+12 

* undraw previous sprit 

drsprite 

equ init+13 

* draw sprite 

copyrstr 

equ init+1 4 

* copy raster form 

seedfill 

equ init+15 

* polygon fill 
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Sprite demonstration 

The following Line-A program is deliberately compressed to show the small 
number of lines of assembler used to control sprites. The program produces an 
alternate black and white sprite crossing a monochrome screen. 


Digital Research 


Hisoft . 


GST 


Metacomco 


Seka 


init 

equ $a000 

* 

unsprite 

equ init+12 

* \ 

drsprite 

* 

equ init+13 

* < 

V_X_MAX 

* 

equ -12 

* 1 

text 

* 



k ; 

start: clr.l -(sp) 

* 

Set 

. 

move . w #$20, - (sp) 

* 

super 

* 

trap #1 

* 

mode 

* 

addq.l #6,sp 

* 


* 

move .1 dO, stksv 

* 

save stack 

k 

move.w #0,olda 

* 

versn flag 

k 

move.l #0,a2 

* 


•k 

dc . w init 

* 

Init 

k 

move.l a2,d2 

* 

aline 

k 

bne a2ok 

* 

registers 

* 

lea #-60 (al) , a2 

* 


* 

move.w #-l,olda 

* 

* 


* 

a2ok: move.l $34(a2),a3 

* 

draw addr (4*13) 


move . w # V_X_MAX (a0) f 

-a5* get max width 

< 

move.w #0,d0 

* 

init x 

* 

move.w #50, dl 

* 

init y 

* 

move.w #10, d2 

* 

scan count 

k 

lea sprit, aO 

* 

sprite add 

k 

lea save,a2 

* 

bg savearea 

k 

movea.l a0,a4 

* 

sprite col 

k 

adda . 1 #6, a 4 

* 

* 

pointer 

k 

setcol: move.w (a4),d3 

* 

get color 

k 

bne white 

* 


k 

move.l #$00010001 

, (a4) * black 

k 

bra loop 

* 

color 

k 

white: move.l #0, (a4) 

* 

set white 

k 

loop: movem.l d0-d2/a0-i 

a4 , 

. - (sp) *sav r 

k 

tst . w olda 

* 

test versn 

* 

beq new 

* 


k 

jsr (a3) 

* 

old versn 

k 

bra cont 

* 


k 

new: dc.w drsprite 

* 

new versn 

k 

cont: move.w #2000, dO 

* 


k 


initialize init: . 
undraw sprite unsprite: 
draw sprite drsprite: 


section c 


*3 

*] 

.*] 

*] 

.*] 


-60 (al) , a2 


V X MAX ( a 0 ) , a5 
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* Digital Research 


* 


Hisoft 


GST 


dbra dO/wait 

* 

delay 

* 

lea save,a2 

* 

bg savarea 

* 

dc.w unsprite 

* 


* 

movem.l (sp) +, d0-d2/a0-a4* unsave r 

* 

add.w #l,d0 

* 

slide over 

* 

cmp.w a5,d0 

* 

screen 

* 

ble loop 

* 


* 

move.w #0,d0 

* 

init x 

* 

add.w #10, dl 

* 

drop y 

* 

sub.w #l,d2 

* 

count down 

* 

bne setcol 

■k 

and again 

* 

move.l stksv,-(sp) 

k 

back 

★ 

move.w #$20, - (sp) 

* 

to 

* 

trap #1 

* 

user 

•k 

addq. 1 #6, sp 

* 

mode 

k 

move . w #0, - (sp) 

* 

back 

k 

trap #1 

★ 

to GEM 

k 


Metacomco Seka 


*3 

*3 

*3 


*3 


data 

even 

* 

sprit: dc.w 0,0 
dc.w -1 
dc.w 0 
dc . w 0 

ghoul: dc.w $ffff 
dc.w $03c0 
dc.w $ f f f f 
dc.w $0ff0 
dc.w $ffff 
dc.w $lf f 8 
dc.w $ffff 
dc.w $3ffc 
dc.w $ffff 
dc.w $73ce 
dc.w $ffff 
dc.w $73ce 
dc.w $ffff 
dc.w $ffff 
dc.w $ffff 
dc.w $ffff 
dc.w $ffff 
dc.w $fbdf 
dc.w $ffff 
dc.w $f 81f 
dc.w $ f f f f 
dc.w $ffff 
dc.w $ffff 
dc.w $67e6 


* xxx 

* xxx 


section d 
. xxx 


xxx 


* X/ y * 

* l_vdi, -l_xor 

* bg col * 

* fg col * 

* 


* 


xxx 

xxx 
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* Digital Research 

* 

dc.w Sffff 
dc.w $3 00c 
dc.w Sffff 
dc.w Slf f 8 
dc.w Sffff 
dc.w S0420 
dc.w Sffff 
dc.w $1818 

* 

bss 

even 

* 

stksv: ds . 1 1 
save: ds.b 74 
olda: ds.w 1 
★ 

end 


Hisoft . GST Metacomco Seka 


* xxx section d . data 

* xxx . xxx . xxx . xxx 

* blk.l . *1 

* blk.b . 

* blk.w . *2 


*1 There is no requirement to run this program in supervisor mode, these 
lines of code may be omitted. 

*2 Some versions of the disk based TOS incorrectly return the value of A2. 
These lines of code are not required by ROM based versions of the ST. 

*3 The use of the following code provides more stable sprites: 

MOVE #37, -(sp) * wait for vblank 

TRAP #14 * XBIOS call 

ADDQ #2/Sp * tidy stack 


The programmer might also contemplate hiding the busy-bee cursor. 
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ADE ASCII decimal equivalent 

AES Application environment services 

ACIA Asynchronous communications interface adaptor 

ANSI American national standards institute 

ASCII American standard code for information interchange 

AUX Auxilary 

BCD Binary coded decimal 

BDOS Basic disk operating system 

BIOS Basic input /output system 

BPB BIOS parameter block 

BSS Block storage segment 

CCP Console command processor 

CCR Condition code register 

CON Console 

CP/M Control program for microcomputers 

CPU Central processing unit 

CRC Cyclic redundancy check 

CTS Clear to send 

DCD Data carrier detect 

DIR Directory 

DMA Direct memory access 

DOS Disk operating system 

DPB Disk parameter block 

DS Double sided 

DTR Data terminal ready 

D/A Digital to analogue 

EPB Exception parameter block 

FAT File allocation table 

FCB File control block 

FDC Floppy disk controller 

FIFO First in, first out register 

GDOS Graphics device operating system 

GEM Graphics environment manager 

GIOS Graphics input/ output system 

GP General purpose 

Grd Ground 

GSX Graphic system extension 
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HDC 

Hard disk controller 


ID 

Identification 


ikbd 

Intelligent keyboard 


IPL 

Interrupt level 


I/O 

Input/output 


LPB 

Load parameter block 


LSB 

Least significant byte/bit 


LST 

List 


MD 

Memory descriptor 


MFDB 

Memory form definition block 


MFP 

Multi function peripheral 


MIDI 

Musical instruments digital interface 


MS-DOS 

Microsoft disk operating system 


MSB 

Most significant bit 


NDC 

Normalized device coordinates 


OEM 

Other equipment manufacturer 


OS 

Operating system 


OSC 

Oscillator 


PC 

PC-DOS 

Program counter 

IBM personal computer operating system 


pk-pk 

PSG 

Peak to peak 

Programmable sound generator 


RAM 

Random access memory 


RC 

Raster coordinate 


RF 

Radio frequency 


RGB 

Red-green-blue 


Ri 

Ring 


ROM 

Read only memory 


RSX 

Resident system extension 


RTE 

Return from exception 


RTS 

Return from subroutine 


Rx 

Receive 
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SASI Shugart associates standard interface 

SCSI Small computer systems interface 

SP Stack pointer 

SR Status register 

SS Single sided 

SSP Supervisor stack pointer 

TOS The operating system 

TPA Transient program area 

TTL Transistor-transistor logic 

Tx Transmit 

ULA Uncommitted logic array 

USART Universal synchronous / asynchronous receiver-transmitter 

USP User stack pointer 

VBI Vertical blank interrupt 

VDI Virtual device interface 

VLSI Very large scale integration 
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Atari ST schematic diagram 
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